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:
curl -sS "$BUSINESS_API/customers?after=not-a-cursor" \
-H "Authorization: Bearer $API_KEY"
{
"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:
{
"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#
- Decida pelo
error_code. Se o seu cliente não o conhecer, use ocode, que tem um valor por omissão para cada caso (INVALID_REQUESTcorresponde arequest.invalid,UNAUTHORIZEDaauth.unauthenticated,NOT_FOUNDaresource.not_found). - Nunca compare o texto de
detail: pode mudar sem aviso. - Repita apenas os problemas marcados como temporários:
RATE_LIMITED(429),INTEGRATION_UNAVAILABLE(503),DEADLINE_EXCEEDED(504) eINTERNAL_ERROR(500). NumPOST, repita com o mesmoIdempotency-Key. Os restantes4xxvoltam a falhar enquanto o pedido não mudar. - Guarde o
request_idnos seus registos. Pode também enviar o seu próprio identificador no cabeçalhoRequest-Id(ouX-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 formatoreq_seguido de 32 caracteres hexadecimais.