Tratamento de Erros

Todas as respostas de erro da API seguem um formato JSON padronizado para facilitar o tratamento programático.

Formato do Erro

{
  "errorCode": "missing_tenant",
  "message": "X-Tenant-Id header is required"
}

Catálogo Geral de Erros

Code	HTTP	Descrição
missing_tenant	400	O header X-Tenant-Id é obrigatório e não foi informado.
missing_idempotency_key	400	A operação requer o header Idempotency-Key.
invalid_payload	400	O corpo da requisição (JSON) é inválido ou contém erros de validação.
idempotency_conflict	409	A chave de idempotência já foi utilizada com um corpo de requisição diferente.
forbidden	403	Você não tem permissão para realizar esta ação no recurso solicitado.
invalid_signature	401	A assinatura fornecida (HMAC) é inválida ou o timestamp expirou.
authz_error	500	Erro interno ao verificar permissões de autorização.
partner_error	502	Ocorreu um erro na comunicação com o provedor bancário.
internal_error	500	Ocorreu um erro inesperado em nossos servidores.

Erros Específicos de Negócio

PIX Out (Transferências)

Code	HTTP	Descrição
insufficient_balance	400	Saldo disponível insuficiente para a operação. A mensagem inclui detalhes: saldo total, bloqueado e valor solicitado.
invalid_key_type	400	O keyType informado é inválido. Valores aceitos: CPF, CNPJ, EMAIL, PHONE, EVP.
invalid_emv	400	A string EMV do QR Code é inválida ou malformada.
pix_limit_exceeded	400	O valor da transação excede os limites configurados para a conta.

QR Codes

Code	HTTP	Descrição
pix_qr_not_found	404	O QR Code solicitado não foi encontrado ou já expirou.
pix_qr_already_paid	409	O QR Code dinâmico já foi pago.
pix_qr_expired	400	O QR Code dinâmico expirou e não pode mais ser pago.
pix_qr_cancelled	400	O QR Code foi cancelado e não pode mais ser pago.

Chaves PIX

Code	HTTP	Descrição
pix_key_not_found	404	A chave PIX informada não foi encontrada no DICT.
pix_key_already_exists	409	A chave PIX já está registrada em outra conta.
pix_key_limit_exceeded	400	O limite de chaves PIX por conta foi atingido.

Devoluções

Code	HTTP	Descrição
refund_not_allowed	400	A devolução não é permitida para esta transação (ex.: o prazo expirou).
refund_amount_exceeded	400	O valor da devolução excede o valor da transação original.
original_transaction_not_found	404	A transação original (originalEndToEnd) não foi encontrada.

MED (Mecanismo Especial de Devolução)

Code	HTTP	Descrição
med_not_found	404	O MED especificado não foi encontrado.
med_already_answered	409	O MED já foi respondido.
med_deadline_expired	400	O prazo para responder ao MED expirou.

Exemplos de Erros Comuns

Saldo Insuficiente

{
  "errorCode": "insufficient_balance",
  "message": "insufficient available balance: 50.00 (total: 100.00, locked: 50.00, requested: 150.00)"
}

Tipo de Chave Inválido

{
  "errorCode": "invalid_payload",
  "message": "keyType must be one of: CPF, CNPJ, EMAIL, PHONE, EVP"
}

Conflito de Idempotência

{
  "errorCode": "idempotency_conflict",
  "message": "Request with same Idempotency-Key but different payload"
}

EMV Inválido

{
  "errorCode": "invalid_payload",
  "message": "emv is required"
}

Monitoramento e Suporte

Se você receber erros 5xx frequentes (Internal Error ou Partner Error), recomendamos:

1. Implementar retry exponencial com a mesma chave de idempotência (máximo de 3 tentativas).
2. Verificar o status da nossa plataforma em caso de indisponibilidade prolongada.
3. Entrar em contato com o suporte informando:
   • O errorCode recebido
   • O payload enviado (sem dados sensíveis)
   • O X-Request-Id da resposta (se disponível)
   • Timestamp aproximado do erro

Canais de Suporte

• Slack: Canal privado por cliente — solicite acesso durante o onboarding.
• Email: support@corpxapi.com