> ## Documentation Index
> Fetch the complete documentation index at: https://docs.besimplo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Erros e respostas HTTP

> Códigos que a API retorna, formato das mensagens de erro e como tratar cada situação.

A API Simplo retorna erros no padrão [RFC 7807 (Problem Details for HTTP APIs)](https://www.rfc-editor.org/rfc/rfc7807) com `Content-Type: application/problem+json`.

```json theme={null}
{
  "type": "https://problems-registry.smartbear.com/validation-error",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "The request payload contains validation errors",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "detail": "Campo obrigatório não informado", "pointer": "/customer/name" }
  ]
}
```

| Campo    | O que é                                                                                                                    |
| -------- | -------------------------------------------------------------------------------------------------------------------------- |
| `type`   | URI que identifica o tipo de problema                                                                                      |
| `status` | Código HTTP (espelha o status da resposta)                                                                                 |
| `title`  | Título legível do problema                                                                                                 |
| `detail` | Descrição específica para esta ocorrência                                                                                  |
| `code`   | Código de erro estável da Simplo (use para lógica programática)                                                            |
| `errors` | Lista de erros de campo (presente em validação) — cada item tem `detail` e `pointer` (JSON Pointer apontando para o campo) |

## Códigos de status

| Código                      | Significado                                          | Ação recomendada                                  |
| --------------------------- | ---------------------------------------------------- | ------------------------------------------------- |
| `200 OK`                    | Sucesso na leitura ou atualização                    | —                                                 |
| `201 Created`               | Recurso criado                                       | Guarde o `id` da resposta                         |
| `204 No Content`            | Sucesso sem corpo (ex.: delete)                      | —                                                 |
| `400 Bad Request`           | Requisição malformada (JSON inválido, header errado) | Corrija o cliente HTTP                            |
| `401 Unauthorized`          | Chave de API ausente, inválida ou revogada           | [Verifique sua autenticação](/guias/autenticacao) |
| `403 Forbidden`             | Chave válida, mas sem permissão para o recurso       | Confira se a chave é da conta certa               |
| `404 Not Found`             | Recurso não existe ou pertence a outra conta         | Confira o `id`                                    |
| `422 Unprocessable Entity`  | Dados não passaram na validação ou regra de negócio  | Veja `errors` ou `detail` para corrigir           |
| `429 Too Many Requests`     | Rate limit estourado                                 | Aguarde e tente novamente — veja abaixo           |
| `500 Internal Server Error` | Algo deu errado do nosso lado                        | Tente novamente; se persistir, fale com o suporte |
| `503 Service Unavailable`   | Manutenção ou indisponibilidade temporária           | Tente novamente com backoff                       |

## Validação (422)

Quando você envia dados inválidos, a resposta detalha **cada campo problemático** em `errors[]`:

```json theme={null}
{
  "type": "https://problems-registry.smartbear.com/validation-error",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "The request payload contains validation errors",
  "code": "VALIDATION_ERROR",
  "errors": [
    { "detail": "Campo obrigatório não informado", "pointer": "/customer/name" },
    { "detail": "deve ter 11 dígitos (CPF) ou 14 (CNPJ)", "pointer": "/customer/identifier" }
  ]
}
```

Use `pointer` (JSON Pointer) para mostrar a mensagem ao lado do campo correto no seu formulário.

## Regra de negócio (422)

Nem todo `422` é validação de campo. Algumas regras são de negócio — nesse caso, `code` identifica a regra e `detail` traz a explicação:

```json theme={null}
{
  "type": "https://problems-registry.smartbear.com/business-rule-violation",
  "status": 422,
  "title": "Unprocessable Entity",
  "detail": "Modo de checkout inválido. Modos válidos: 'subscription', 'payment'",
  "code": "INVALID_MODE"
}
```

## Autenticação (401)

```json theme={null}
{
  "type": "https://problems-registry.smartbear.com/unauthorized",
  "status": 401,
  "title": "Unauthorized",
  "detail": "Chave de API inválida ou ausente.",
  "code": "UNAUTHORIZED"
}
```

Causas comuns:

* Header faltando o prefixo `ApiKey ` (com espaço).
* Chave revogada no painel.
* Usando chave de sandbox em produção (ou vice-versa).

## Rate limit (429)

```json theme={null}
{
  "type": "https://problems-registry.smartbear.com/too-many-requests",
  "status": 429,
  "title": "Too Many Requests",
  "detail": "Limite de requisições excedido. Tente novamente em alguns instantes.",
  "code": "RATE_LIMITED"
}
```

A resposta inclui o header `Retry-After` em segundos. Implemente **backoff exponencial**:

```ruby theme={null}
# Ruby
def with_retry(max_attempts: 5)
  attempts = 0
  begin
    attempts += 1
    yield
  rescue Simplo::RateLimit => e
    raise if attempts >= max_attempts
    sleep(e.retry_after || 2 ** attempts)
    retry
  end
end
```

<Warning>
  Não faça **retry imediato** em loop apertado. Isso piora o problema e pode estender o bloqueio.
</Warning>

## Erros do servidor (5xx)

`500` e `503` são raros, mas acontecem. Trate-os como **transitórios**:

1. Espere alguns segundos.
2. Tente de novo com **backoff exponencial**.
3. Se persistir por mais de 5 minutos, verifique [status.besimplo.com](https://status.besimplo.com).

<Warning>
  Como a API ainda **não suporta `Idempotency-Key`** em requisições, retries em operações financeiras (`POST /checkout/sessions`, `POST /refunds`, etc.) podem gerar duplicidade. Em caso de timeout numa operação que mexe em dinheiro, **consulte o recurso antes de retentar** para confirmar se ele já foi criado.
</Warning>