Erros
Formato Problem Details, códigos HTTP e X-Request-Id.
Todo erro da API sai no formato Problem Details (RFC 9457, sucessora da RFC 7807), com
Content-Type: application/problem+json:
{
"title": "Bad Request",
"status": 400,
"detail": "Invalid request content.",
"instance": "/payments",
"errors": [
{ "field": "dueDate", "message": "deve ser uma data no presente ou no futuro" },
{ "field": "payer.document", "message": "deve ser um CPF ou CNPJ só com dígitos" }
]
}detailexplica o erro em texto. Não faça parse dele: use ostatuse, em erros de validação, a listaerrors(fieldemessage).- Em erro de validação, as mensagens não repetem o valor enviado, para não ecoar dados pessoais.
Códigos HTTP
| Status | Significado | O que fazer |
|---|---|---|
400 | Requisição inválida: campo faltando, formato errado, JSON malformado ou Idempotency-Key ausente | Corrija a requisição; não repita igual. |
401 | Token ausente, inválido ou expirado | Gere um token novo. Veja Autenticação. |
403 | Token sem o escopo da operação | Peça o escopo pelo Atendimento. |
409 | Requisição com a mesma Idempotency-Key ainda em andamento | Aguarde e repita com a mesma chave. |
422 | Dados recusados pelo provedor de pagamento, ou Idempotency-Key reutilizada com outro corpo | Corrija os dados; veja o detail. |
429 | Limite de requisições excedido | Aguarde o Retry-After. Veja Rate limit. |
502 | Falha ao falar com o provedor de pagamento | Veja Depois de um erro 5xx. |
503 | Forma de pagamento indisponível no momento | Tente mais tarde. |
500 | Erro inesperado | Abra um chamado com o X-Request-Id. |
X-Request-Id
Toda resposta, de sucesso ou de erro, traz o header X-Request-Id, que identifica a chamada nos nossos
logs. Registre-o no seu sistema e informe-o ao abrir um chamado no Atendimento.
Você também pode enviar o seu próprio id no header X-Request-Id (até 64 caracteres: letras, números, .,
_ e -). A API usa o seu valor e o devolve na resposta, o que ajuda a cruzar os logs dos dois lados. Fora
desse formato, a API gera um id novo.