Formato de erro
Todo erro vem no mesmo envelope, com o status HTTP igual ao statusCode. O seu código decide pelo error.code; a message é para pessoas.
O envelope
| Campo | O que é |
|---|---|
success | Sempre false. |
message | Explicação em português, para mostrar ou registrar. Pode mudar de texto: não compare. |
statusCode | O mesmo status da resposta HTTP. |
error.code | O código em inglês, em maiúsculas. Estável: é ele que o seu código compara. |
error.details | Opcional. Uma lista de campos (erros de validação) ou um objeto com o contexto do erro. |
O que vem em details
VALIDATION_ERROR: uma lista de{ path, message }.pathaponta o campo no corpo, como/amount,/customer/document/numberou/destination/key.- Erros de regra trazem o dado que ajuda a corrigir:
refundableemREFUND_EXCEEDS_REFUNDABLE,feeemAMOUNT_TOO_LOW,statusemCHARGE_NOT_OPEN,chargeIdemEXTERNAL_ID_CONFLICTde cobrança,beneficiaryIdnoCONFLICTde beneficiário repetido,retryAfterSecondsemRATE_LIMITED. - Sem nada a acrescentar, error vem só com code.
RISK_DECLINED nunca diz o motivo, de propósito. Erros internos (INTERNAL_ERROR) também não trazem detalhe: mande o X-Request-Id da resposta ao suporte.
Como reagir
| Status | O que fazer |
|---|---|
400 · 422 | O pedido não passou. Corrija o corpo, o cabeçalho ou o parâmetro apontado; repetir igual dá o mesmo erro. |
401 · 403 | A chave, o escopo, o IP ou a situação da empresa. Não adianta repetir. |
404 | NOT_FOUND: o recurso não existe nesta empresa e neste ambiente. ROUTE_NOT_FOUND: a rota não existe. |
409 | Conflito com o estado de agora (já cancelado, já decidido, chave reaproveitada). Consulte o recurso antes de decidir. |
429 | Limite de chamadas: espere error.details.retryAfterSeconds. |
500 · 503 | Do nosso lado ou de um provedor. Repita depois, com a mesma Idempotency-Key: resposta 5xx não fica guardada. Em cobranças, mande também o externalId: se algo chegou a ser criado, a repetição devolve o existente. |
Corpo que não é JSON válido responde 400 INVALID_JSON. Todos os códigos, com o status de cada um, estão em Códigos.