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": {
    "status": "Bad Request",
    "statusCode": 400,
    "category": "validation",
    "code": "invalidParameters",
    "message": "Validation errors occurred.",
    "resource": "transaction",
    "details": "Informações adicionais sobre o erro",
    "params": [
      {
        "field1": "Mensagem de erro específica para o campo"
      }
    ]
  }
}

O campo error.resource está sempre presente e indica o domínio dono do erro (ex.: transaction, customer, server).

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:

Rate limit (429): o tempo de espera é informado no cabeçalho HTTP Retry-After (em segundos), não no corpo. O envelope JSON do 429 não traz retryAfter/retryAfterMinutes.

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": "authentication",
    "code": "unauthorized",
    "message": "Authentication is required to access this resource.",
    "resource": "server"
  }
}

Casos Comuns

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

402 - Payment Required

Indica recusa/falha no processamento do pagamento (category: "payment"). O envelope segue a mesma estrutura padrão (status, statusCode, category, code, message, resource).

{
  "error": {
    "status": "Payment Required",
    "statusCode": 402,
    "category": "payment",
    "code": "paymentDeclined",
    "message": "The payment was declined by the issuer.",
    "resource": "payorch"
  }
}

⚠️ Importante: a criação de uma transação (POST /v1/transactions) é assíncrona — ela responde 201 Created com status: "pending" e a cobrança é processada em segundo plano. Uma recusa de cartão normalmente não chega como um 402 síncrono nessa chamada; o resultado da cobrança aparece no objeto da transação (status: "failed") e no webhook transaction.failed. Veja Recusas de Pagamento.

Casos Comuns

• Cobrança recusada pelo emissor/adquirente
• Falha no processamento do pagamento

403 - Forbidden

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

{
  "error": {
    "status": "Forbidden",
    "statusCode": 403,
    "category": "authorization",
    "code": "forbidden",
    "message": "You do not have permission to perform this action.",
    "resource": "server"
  }
}

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",
    "code": "transactionNotFound",
    "message": "Transaction not found.",
    "resource": "transaction"
  }
}

O error.code e error.resource variam conforme o recurso consultado (ex.: customerNotFound/customer).

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.

Indica que o método HTTP usado não é permitido para o endpoint (o caminho existe, mas não para esse verbo).

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": "client",
    "code": "idempotencyMismatch",
    "message": "This idempotency key was already used with a different request payload.",
    "resource": "server"
  }
}

Casos Comuns

• Violação de restrição de idempotência (idempotencyMismatch, idempotencyInProgress) — veja 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": "validation",
    "code": "providerNotConfigured",
    "message": "No payment provider is configured for the requested mode.",
    "resource": "payorch"
  }
}

Casos Comuns

• Valores de campos em formato correto, mas semanticamente inválidos
• CPF válido em formato, mas inexistente
• Provedor de pagamento não configurado para o modo solicitado (providerNotConfigured)

A criação de transação é assíncrona: uma recusa de cartão chega como status: "failed" no objeto da transação e no webhook transaction.failed, não como um erro síncrono nessa chamada. 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",
    "code": "tooManyRequests",
    "message": "Too many requests. Please slow down and retry after a short wait.",
    "resource": "server",
    "details": "This endpoint is rate limited. Check the Retry-After response header for when to retry."
  }
}

O tempo de espera vem no cabeçalho HTTP Retry-After (segundos), não no corpo.

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",
    "code": "serverError",
    "message": "An unexpected error occurred. Please try again later.",
    "resource": "server",
    "details": "If the problem persists, contact support with the correlationId from the response headers."
  }
}

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",
    "code": "providerUnavailable",
    "message": "The service is temporarily unavailable. Please try again later.",
    "resource": "server"
  }
}

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:

Conflitos de idempotência (409) usam a categoria client (não há categoria idempotency).

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, provedor não configurado). A criação de transação é assíncrona — recusas de cartão chegam como status: "failed"/webhook transaction.failed, não como erro síncrono. 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 cabeçalho HTTP Retry-After (segundos) 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