Códigos de Erro

🚨 Estrutura de Erro Padrão

{
  "success": false,
  "error": {
    "code": "PAYMENT_FAILED",
    "message": "The payment could not be processed",
    "details": "Insufficient funds on the card",
    "timestamp": "2024-12-12T10:30:00Z",
    "request_id": "req_123456789"
  }
}

🔢 Códigos HTTP

Código	Significado	Quando Usar
200	OK	Operação bem-sucedida
201	Created	Recurso criado
400	Bad Request	Dados inválidos
401	Unauthorized	Não autenticado
403	Forbidden	Sem permissão
404	Not Found	Recurso não encontrado
409	Conflict	Conflito de estado
422	Unprocessable Entity	Dados válidos mas regra de negócio
429	Too Many Requests	Rate limit
500	Internal Server Error	Erro interno
502	Bad Gateway	Provedor indisponível
503	Service Unavailable	Manutenção

💳 Erros de Pagamento

Códigos Principais

Código	Descrição
PAYMENT_FAILED	Pagamento falhou
INSUFFICIENT_FUNDS	Fundos insuficientes
INVALID_CARD	Cartão inválido
CARD_DECLINED	Cartão recusado
EXPIRED_CARD	Cartão expirado
INVALID_CVC	CVC inválido
PROCESSING_ERROR	Erro de processamento
PAYMENT_TIMEOUT	Timeout no pagamento
DUPLICATE_PAYMENT	Pagamento duplicado
REFUND_FAILED	Falha no reembolso

Exemplos

{
  "success": false,
  "error": {
    "code": "CARD_DECLINED",
    "message": "Your card was declined",
    "details": "The issuing bank declined the transaction",
    "decline_code": "generic_decline"
  }
}

🔐 Erros de Autenticação

Código	Descrição
INVALID_TOKEN	Token inválido
EXPIRED_TOKEN	Token expirado
MISSING_TOKEN	Token ausente
INVALID_API_KEY	API key inválida
INSUFFICIENT_PERMISSIONS	Permissões insuficientes
ACCOUNT_SUSPENDED	Conta suspensa

{
  "success": false,
  "error": {
    "code": "EXPIRED_TOKEN",
    "message": "The authentication token has expired",
    "details": "Token expired at 2024-12-12T10:30:00Z"
  }
}

📊 Erros de Validação

Código	Descrição
VALIDATION_ERROR	Erro de validação
MISSING_REQUIRED_FIELD	Campo obrigatório ausente
INVALID_FORMAT	Formato inválido
VALUE_OUT_OF_RANGE	Valor fora do intervalo
INVALID_CURRENCY	Moeda inválida
INVALID_AMOUNT	Valor inválido

{
  "success": false,
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "amount": ["Amount must be greater than 0"],
      "email": ["Invalid email format"]
    }
  }
}

🌐 Erros de Provedor

Stripe

Código	Mapeamento Stripe
CARD_DECLINED	card_declined
EXPIRED_CARD	expired_card
INSUFFICIENT_FUNDS	insufficient_funds
INVALID_CVC	incorrect_cvc
PROCESSING_ERROR	processing_error

PayPal

Código	Mapeamento PayPal
PAYMENT_FAILED	PAYMENT_DENIED
INSUFFICIENT_FUNDS	INSUFFICIENT_FUNDS
INVALID_ACCOUNT	INVALID_ACCOUNT_STATUS

MercadoPago

Código	Mapeamento MP
CARD_DECLINED	cc_rejected_other_reason
INSUFFICIENT_FUNDS	cc_rejected_insufficient_amount
INVALID_CVC	cc_rejected_bad_filled_security_code

🔄 Erros de Rate Limiting

{
  "success": false,
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": "Rate limit of 1000 requests per hour exceeded",
    "retry_after": 3600
  },
  "headers": {
    "X-RateLimit-Limit": 1000,
    "X-RateLimit-Remaining": 0,
    "X-RateLimit-Reset": 1640999999
  }
}

🎣 Erros de Webhook

Código	Descrição
WEBHOOK_VERIFICATION_FAILED	Falha na verificação
WEBHOOK_TIMEOUT	Timeout no webhook
WEBHOOK_PROCESSING_ERROR	Erro no processamento
INVALID_WEBHOOK_PAYLOAD	Payload inválido

🔧 Erros de Sistema

Código	Descrição
INTERNAL_SERVER_ERROR	Erro interno
DATABASE_CONNECTION_ERROR	Erro de conexão BD
EXTERNAL_SERVICE_UNAVAILABLE	Serviço externo indisponível
CONFIGURATION_ERROR	Erro de configuração
MAINTENANCE_MODE	Modo de manutenção

🛠️ Debugging

Request ID

Cada erro inclui um request_id único para rastreamento:

{
  "error": {
    "request_id": "req_abc123def456"
  }
}

Logs Correlacionados

grep "req_abc123def456" /var/log/payment-gateway/application.log

Headers Úteis

X-Request-ID: req_abc123def456
X-Correlation-ID: corr_xyz789
X-Debug-Mode: true  # Para ambiente de desenvolvimento

📱 Códigos por Categoria

Cliente (4xx)

• Erro do usuário/aplicação

• Requer correção do cliente

• Não deve ser reprocessado automaticamente

Servidor (5xx)

• Erro interno do sistema

• Pode ser temporário

• Candidato a retry com backoff

Provedor (502/503)

• Erro do provedor de pagamento

• Geralmente temporário

• Implementar fallback/retry

---

Documentação atualizada: December 2024