Erros
Toda falha da API responde com o mesmo envelope, em qualquer rota e em qualquer status:
{
"error": {
"type": "invalid_request_error",
"code": "amount_too_small",
"message": "amount must be >= 100",
"param": "amount",
"request_id": "req_01J...",
"details": { "min": 100 }
}
}
type, code, message e request_id vêm sempre. param aparece quando a falha é de um valor
específico do corpo ou da query. details é o único lugar onde cabe dado extra do erro, por exemplo
o saldo que faltou ou o limite que estourou; nada de campo solto fora dele.
Programe contra code, nunca contra message. A mensagem é em inglês, curta, e pode mudar sem
aviso; o código é contrato.
Os oito tipos
type é a família e resolve o tratamento genérico: invalid_request_error,
authentication_error, permission_error, not_found_error, idempotency_error,
rate_limit_error, acquirer_error e internal_error.
A lista completa de code por operação está na referência da API, dentro de cada
resposta de erro. Ela não é repetida aqui de propósito: uma cópia à mão apodrece.
O que fazer com cada classe
Isso é o que a referência não diz. É a leitura operacional dos códigos:
| Classe | Códigos típicos | O que fazer |
|---|---|---|
| Corrigir e repetir | validation_failed, invalid_document, amount_too_small, amount_too_large, invalid_expires_in, invalid_url, unsupported_payment_method, missing_idempotency_key |
Conserte o corpo e repita com a mesma Idempotency-Key. Nada foi criado. |
| Repetir depois | rate_limited, acquirer_timeout, acquirer_rejected, acquirer_unavailable |
Em rate_limited, respeite o Retry-After. Depois de um 503 do processador, tente de novo com chave nova: a resposta de erro ficou gravada na chave antiga. |
| Nunca repetir igual | idempotency_conflict, invalid_state, insufficient_balance, daily_limit_exceeded, pix_key_not_verified |
É decisão de negócio, não falha passageira. Repetir o mesmo pedido dá o mesmo erro. |
| Conferir a chave | invalid_api_key, revoked_api_key, seller_not_allowed, kyc_required, payout_locked |
A chave ou a conta não podem fazer isso agora. Ver Autenticação. |
| Não existe | resource_not_found |
Id errado, de outra conta ou do outro ambiente. Os três respondem igual, de propósito. |
| Falar com a gente | internal_error |
Anote o request_id e abra um chamado. |
idempotency_in_progress é o único 409 que pede retentativa: a sua própria requisição anterior
ainda está rodando. Espere e repita igual.
O request_id
Toda resposta, com erro ou sem, traz o header X-Request-Id, e o mesmo valor aparece em
error.request_id. Ele é o que localiza a requisição exata nos nossos logs.
Registre esse valor junto de todo erro 5xx que você logar. Um chamado com request_id se resolve
em minutos; um chamado com "deu erro ontem à tarde" não se resolve.
Próximo passo
Paginação para as listagens, ou Limites para o que dispara rate_limited
e os tetos de valor e de tamanho.
Referência: Cria uma cobrança PIX é a operação com mais códigos de erro possíveis, e cada
um deles está descrito na resposta correspondente.