# 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

- [Lista completa de códigos de erro](/docs/api/errors)
- [Repetir pedidos sem duplicar com Idempotency-Key](/docs/getting-started/idempotency)
- [Limites de pedidos e respostas 429](/docs/getting-started/rate-limits)

