Códigos HTTP e erros

A API usa os status HTTP convencionais: 2xx é sucesso, 4xx é problema na requisição que você enviou e 5xx é falha do nosso lado.

Formato do erro

Todo erro tem o mesmo corpo:

{
  "statusCode": 400,
  "code": "VALIDATION",
  "message": ["grossAmount must be a string"],
  "traceId": "3b9c6f2a-71d4-4e0b-b8a5-0c2e9f41d7a6"
}

Campo	Descrição
`statusCode`	O mesmo status HTTP da resposta.
`code`	Código estável para o seu sistema tratar o erro. Use este campo nas decisões, não a mensagem.
`message`	Texto para pessoas. Pode ser string ou lista (erros de validação trazem um item por campo). Pode mudar sem aviso.
`traceId`	Identificador do erro nos nossos registros. Informe ao suporte para localizar o caso.
`missing`	Opcional. Lista dos dados que faltam para concluir a operação.

Status	`code`	Significado
`200`, `201`	—	Sucesso. `201` quando um recurso é criado.
`400`	`BAD_REQUEST`, `VALIDATION`	Campo obrigatório ausente ou inválido. A `message` diz qual.
`401`	`UNAUTHORIZED`	Chave de API ausente ou inválida. Veja Autenticação.
`403`	`FORBIDDEN`, `API_KEY_IP_NOT_ALLOWED`	Operação não permitida para a conta, chamada de IP não liberado, ou `GET` enviado com corpo.
`404`	`NOT_FOUND`	O endpoint ou o recurso não existe (ou não pertence à sua conta).
`409`	`CONFLICT`	O estado atual impede a operação: cliente duplicado, assinatura já cancelada, cobrança já reembolsada.
`422`	`VALIDATION`	Os dados têm o formato certo, mas não passam numa regra de negócio.
`429`	—	Limite de requisições excedido. Veja Limites.
`500`	`INTERNAL`	Erro do nosso lado. A `message` é genérica de propósito; guarde o `traceId`.
`501`	—	Combinação não suportada, por exemplo um plano que mistura PIX e cartão.
`503`	`UNAVAILABLE`	Serviço temporariamente indisponível. Tente de novo com espera crescente.

GET com corpo é recusado

Chamadas GET com qualquer conteúdo no corpo recebem 403. Envie filtros na query string.

429, 500, 503 e timeouts: tente de novo com espera crescente (1 s, 2 s, 4 s…).
Na criação de cobrança, envie attemptIdempotencyKey. Se a nova tentativa responder 409, a primeira chegou a ser criada: consulte a cobrança pelo seu externalReference em vez de criar outra.
4xx (exceto 429): não repita a mesma requisição. Corrija o que a message aponta.