PT EN

Erros

O formato application/problem+json das respostas de erro, a diferença entre code e error_code, os parâmetros de validação, o Request-Id e que erros vale a pena repetir.

Qualquer resposta 4xx ou 5xx da API tem Content-Type: application/problem+json e segue o formato da RFC 9457. O corpo diz o que falhou de três formas: um código geral por tipo de problema (code), um código estável e específico para traduzir e tratar (error_code) e um texto em inglês para quando o código não é reconhecido (detail). Os endpoints OAuth em /oauth/ são a excepção: respondem no formato OAuth, com error e, por vezes, error_description.

Exemplo de pedido e resposta#

Um cursor de paginação inválido é recusado antes de qualquer leitura:

bash
curl -sS "$BUSINESS_API/customers?after=not-a-cursor" \
  -H "Authorization: Bearer $API_KEY"
json
{
  "type": "about:blank",
  "title": "Invalid Request",
  "status": 400,
  "detail": "invalid pagination cursor",
  "instance": "$BUSINESS_API/customers",
  "code": "INVALID_REQUEST",
  "error_code": "request.cursor_invalid",
  "request_id": "req_4e8a1c7f3b9d42e6a0c5f8b2d7e1a693"
}

Os campos#

Campo Conteúdo
type Endereço da explicação do erro, /docs/api/errors#<error_code> na origem do site, quando o operador a configurou. Sem essa configuração vale about:blank.
title Nome curto do problema geral, por exemplo Invalid Request ou Unauthorized.
status O mesmo código HTTP da resposta.
detail Texto em inglês para quem lê registos. Quando o texto revelaria a base de dados ou o código interno do servidor, é substituído por uma frase genérica para o estado HTTP; um 500 traz sempre uma frase genérica.
instance O caminho do pedido.
code O problema geral, em maiúsculas: INVALID_REQUEST, UNAUTHORIZED, FORBIDDEN, NOT_FOUND, CONFLICT, RATE_LIMITED, entre outros.
error_code O código específico, em minúsculas e com pontos, como validation.too_long ou invoice.not_open. Um código publicado nunca muda de nome.
params Valores para compor a mensagem, como field, min e max. Só aparece quando o erro os tem.
request_id O identificador do pedido, igual ao cabeçalho Request-Id.
invalid_params Lista de campos recusados, cada um com name, reason e, quando existe, code.

Erros de validação#

Criar uma chave de API com um nome de mais de 128 caracteres devolve os limites em params, prontos para uma mensagem traduzida:

json
{
  "type": "about:blank",
  "title": "Invalid Request",
  "status": 400,
  "detail": "name is required and at most 128 characters",
  "instance": "$BUSINESS_API/developer/api-keys",
  "code": "INVALID_REQUEST",
  "error_code": "validation.length_out_of_range",
  "params": { "field": "name", "min": "1", "max": "128" },
  "request_id": "req_7b2d9f4a1e6c40b8a3d5e9c2f1a8b046"
}

Como tratar um erro#

  1. Decida pelo error_code. Se o seu cliente não o conhecer, use o code, que tem um valor por omissão para cada caso (INVALID_REQUEST corresponde a request.invalid, UNAUTHORIZED a auth.unauthenticated, NOT_FOUND a resource.not_found).
  2. Nunca compare o texto de detail: pode mudar sem aviso.
  3. Repita apenas os problemas marcados como temporários: RATE_LIMITED (429), INTEGRATION_UNAVAILABLE (503), DEADLINE_EXCEEDED (504) e INTERNAL_ERROR (500). Num POST, repita com o mesmo Idempotency-Key. Os restantes 4xx voltam a falhar enquanto o pedido não mudar.
  4. Guarde o request_id nos seus registos. Pode também enviar o seu próprio identificador no cabeçalho Request-Id (ou X-Request-Id), com até 128 caracteres ASCII visíveis; o servidor usa-o na resposta e nos registos. Sem ele, o servidor gera um no formato req_ seguido de 32 caracteres hexadecimais.

Próximos passos#