Tratamento de Erros

Visão Geral

A API Selectwin utiliza códigos de status HTTP padrão e uma estrutura de resposta de erro consistente para comunicar problemas durante o processamento das requisições. Este documento detalha os diferentes tipos de erros que podem ocorrer, como interpretá-los e as melhores práticas para lidar com eles em sua aplicação.

📖 Para a lista de valores de error.code por recurso (com o status HTTP de cada um), veja o Catálogo de Códigos de Erro.

Estrutura da Resposta de Erro

Todas as respostas de erro da API Selectwin seguem uma estrutura padrão:

{
  "error": {
    "code": "validationError",
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation error occurred.",
    "details": "Informações adicionais sobre o erro",
    "params": [
      {
        "field1": "Mensagem de erro específica para o campo"
      }
    ]
  }
}

Use error.code para a lógica do seu sistema. Ele é o identificador estável e legível por máquina do erro (ex.: validationError, resourceNotFound, rateLimitExceeded). Diferentemente de message/status/details — textos que podem mudar —, o code faz parte do contrato da API e está sempre presente.

Campos Comuns

Campos Específicos

Dependendo do tipo de erro, campos adicionais podem estar presentes:

Códigos de Status HTTP

A API Selectwin utiliza os seguintes códigos de status HTTP para indicar erros:

Erros do Cliente (4xx)

Erros do Servidor (5xx)

Detalhes dos Erros

400 - Bad Request

Indica que a requisição é inválida, geralmente devido a problemas de validação.

{
  "error": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "message": "Validation error occurred.",
    "params": [
      {
        "field1": "Mensagem de erro específica para o campo"
      }
    ]
  }
}

Casos Comuns

• Dados de entrada em formato incorreto
• Campos obrigatórios ausentes
• Valores inválidos para determinados campos

401 - Unauthorized

Indica problemas com a autenticação.

{
  "error": {
    "status": "Unauthorized",
    "statusCode": 401,
    "category": "client",
    "message": "Inactive or expired authorization key",
    "details": "The provided 'selectkey' in the request header is either inactive or expired. Please generate a new key from the dashboard and try again."
  }
}

Casos Comuns

• Chave API ausente ou inválida
• Chave API expirada
• Credenciais incorretas

402 - Payment Required (Recusa de Cartão)

Indica que uma cobrança no cartão foi recusada pelo emissor/adquirente. O envelope traz o motivo em error.code, uma mensagem pronta para o comprador em error.displayMessage (pt-BR) e o flag error.reversible.

{
  "error": {
    "status": "Request Failed",
    "statusCode": 402,
    "category": "payment",
    "code": "insufficientFundsError",
    "type": "cardError",
    "message": "The request was valid, but the payment process failed.",
    "details": "Please verify your payment information and try again.",
    "displayMessage": "Saldo insuficiente para realizar esta compra. Verifique seu limite disponível.",
    "reversible": false
  }
}

A taxonomia completa de códigos de recusa, a semântica de reversible e o webhook transaction.failed estão em Recusas de Pagamento.

Casos Comuns

• Fundos/limite insuficientes (insufficientFundsError)
• Cartão recusado pelo banco (cardDeclined)
• Cartão vencido (expiredCardError)

403 - Forbidden

Indica que o cliente não tem permissão para acessar o recurso solicitado.

{
  "error": {
    "status": "Forbidden",
    "statusCode": 403,
    "category": "client",
    "message": "API Access Denied",
    "details": "The company associated with the request does not have permission to access the API. Please verify the company's API access permissions or contact support for assistance."
  }
}

Casos Comuns

• Plano de assinatura não permite acesso ao recurso
• Restrições de IP
• Permissões insuficientes para a operação solicitada

404 - Not Found

Indica que o recurso solicitado não existe.

{
  "error": {
    "status": "Not Found",
    "statusCode": 404,
    "category": "client",
    "message": "Resource Not Found",
    "details": "The requested resource was not found. Please verify the resource identifier and try again."
  }
}

Casos Comuns

• ID de recurso inexistente
• URL incorreta
• Recurso excluído

405 - Method Not Allowed

Indica que o método HTTP usado não é permitido para o endpoint.

{
  "error": {
    "status": "Method Not Allowed",
    "statusCode": 405,
    "category": "client",
    "message": "Request Method Not Allowed",
    "details": "The HTTP method 'POST' is not allowed for this API. The vendor associated with the request does not have permission to use this method. Please contact support to verify allowed methods or update your permissions."
  }
}

Casos Comuns

• Tentativa de usar POST em um endpoint que só aceita GET
• Método HTTP não suportado para o recurso

409 - Conflict

Indica um conflito com o estado atual do recurso.

{
  "error": {
    "status": "Conflict",
    "statusCode": 409,
    "category": "idempotency",
    "message": "Resource Conflict",
    "details": "The request cannot be completed due to a conflict with the current state of the resource. Please verify the request parameters and try again.",
    "retryAfterMinutes": 60,
    "blockedUntil": "2024-01-01T00:00:00Z",
    "docUrl": "https://docs.selectwin.io/idempotency"
  }
}

Casos Comuns

• Violação de restrição de idempotência
• Tentativa de criação duplicada de recurso
• Condições de concorrência
• Conflito com regras de negócio

422 - Unprocessable Entity

Indica que a requisição está bem formada, mas não pode ser processada devido a erros semânticos.

{
  "error": {
    "status": "Unprocessable Entity",
    "statusCode": 422,
    "category": "client",
    "message": "Unprocessable Entity",
    "details": "The request cannot be processed due to validation errors. Please check the request parameters and try again."
  }
}

Casos Comuns

• Valores de campos em formato correto, mas semanticamente inválidos
• CPF válido em formato, mas inexistente
• Dados de boleto inválidos na geração (serverApiError)

Recusas de cartão (cartão expirado, fundos insuficientes, etc.) não são 422 — retornam 402. Veja Recusas de Pagamento.

429 - Too Many Requests

Indica que o cliente excedeu o limite de requisições permitido.

{
  "error": {
    "status": "Too Many Requests",
    "statusCode": 429,
    "category": "rate_limit",
    "message": "Rate limit exceeded.",
    "details": "You have exceeded the allowed requests per minute.",
    "retryAfterMinutes": 60
  }
}

Casos Comuns

• Muitas requisições em curto período
• Excedeu quota de uso da API

500 - Internal Server Error

Indica um erro inesperado no servidor.

{
  "error": {
    "status": "Internal Server Error",
    "statusCode": 500,
    "category": "server",
    "message": "Internal Server Error",
    "details": "An unexpected error occurred on the server. The issue has been reported to the technical team and will be addressed as soon as possible. Please try again later."
  }
}

Casos Comuns

• Falhas inesperadas no servidor
• Problemas de infraestrutura
• Bugs no sistema

503 - Service Unavailable

Indica que o serviço está temporariamente indisponível.

{
  "error": {
    "status": "Service Unavailable",
    "statusCode": 503,
    "category": "server",
    "message": "Service Unavailable",
    "details": "The server is temporarily unable to service your request due to maintenance downtime or capacity problems. Please try again later."
  }
}

Casos Comuns

• Manutenção programada
• Sobrecarga do sistema
• Falha em serviços dependentes

Categorias de Erro

A API Selectwin agrupa os erros nas seguintes categorias:

Perguntas Frequentes

Como devo lidar com erros 5xx?

Erros 5xx indicam problemas no servidor. Para estes casos:

1. Implemente retry com backoff para tentativas automáticas
2. Tenha um plano de fallback para operações críticas
3. Notifique sua equipe de suporte se o problema persistir

Qual é a diferença entre erros 400 e 422?

• 400 (Bad Request): Problemas na sintaxe da requisição ou validação básica (tipos incorretos, campos obrigatórios ausentes)
• 422 (Unprocessable Entity): A requisição está sintaticamente correta, mas há problemas semânticos (ex: CPF inválido, dados de boleto inválidos). Recusas de cartão (ex.: cartão expirado, fundos insuficientes) retornam 402 — ver Recusas de Pagamento.

Como faço para interpretar erros de validação complexos?

Para erros de validação (categoria validation), verifique o campo error.params que contém informações detalhadas sobre cada campo com problema.

O que devo fazer quando recebo um erro 429 (Rate Limit)?

1. Respeite o valor retryAfter retornado na resposta
2. Implemente backoff exponencial para retentativas
3. Considere otimizar seu código para reduzir o número de requisições
4. Se o problema persistir, avalie a necessidade de um plano com limites maiores

Por que estou recebendo erros 409 (Conflict)?

Erros 409 geralmente ocorrem nas seguintes situações:

1. Tentativa de criar um recurso que já existe
2. Uso incorreto de chaves de idempotência
3. Tentativas de atualização concorrente do mesmo recurso
4. Violação de regras de negócio que geram conflitos