Guias/Integração

Erros e códigos HTTP

Envelope de erro, status comuns e como tratar cada caso.

Formato

{
  "data": null,
  "error": {
    "code": "validation_error",
    "message": "amount deve ser maior que zero",
    "status": 400
  },
  "request_id": "req_01HZ…"
}

Programe contra o code. A message é escrita para humano e pode mudar sem aviso.

Status

Status	Significado	O que fazer
`400`	Corpo inválido	Corrija o campo apontado. Repetir igual não resolve
`401`	Chave ausente ou inválida	Confira o header e o ambiente da chave
`403`	Sem permissão na rota	Ajuste as permissões da chave no painel
`404`	Recurso não existe nessa conta	Confira o ID e o ambiente
`409`	Conflito de estado	O recurso já mudou de estado. Consulte antes de agir
`422`	Regra de negócio barrou	Saldo insuficiente, limite, chave PIX inválida
`429`	Limite de requisições	Espere e repita com backoff
`5xx`	Falha do nosso lado	Repita com backoff. Guarde o `request_id`

Repetir com cuidado

Só repita automaticamente 429 e 5xx, com backoff exponencial e um teto de tentativas. Em toda repetição de rota que cria alguma coisa, reenvie a mesma chave de idempotência — senão você cria o recurso duas vezes.

async function comRetentativa<T>(chamada: () => Promise<Response>, tentativas = 4): Promise<Response> {
  let ultima: Response | null = null;
 
  for (let i = 0; i < tentativas; i++) {
    const resposta = await chamada();
    if (resposta.status !== 429 && resposta.status < 500) return resposta;
 
    ultima = resposta;
    await new Promise((r) => setTimeout(r, 2 ** i * 500 + Math.random() * 200));
  }
 
  return ultima!;
}

Registre request_id, status e error.code em toda chamada que falhar. É o suficiente para o suporte reconstruir o caso.

Precisa de ajuda? Fale com o suporte