# Erros

Todo erro da API do Festero é uma resposta `application/problem+json` ([RFC 9457](https://www.rfc-editor.org/rfc/rfc9457)).
O campo `code` é um contrato estável: decida pelo `code`, nunca pelo `title` nem pelo `detail`. Ao pedir ajuda ao suporte,
envie o `requestId` da chamada.

## Formato

```json
{
  "type": "https://developers.festero.com.br/errors#scope_missing",
  "title": "Forbidden",
  "status": 403,
  "detail": "This credential lacks the 'quotes:read' scope required by this resource.",
  "code": "scope_missing",
  "requestId": "6f1c2a9e-0b7d-4c1e-9a52-3e8f7d1c0a44"
}
```

| Campo | Significado |
|---|---|
| `type` | Endereço desta página com a âncora do código, por exemplo `https://developers.festero.com.br/errors#scope_missing`. |
| `title` | Nome curto do status HTTP, em inglês (`Forbidden`, `Not Found`). Não use para decidir nada. |
| `status` | O status HTTP da resposta. |
| `detail` | Explicação em inglês para quem lê o log. O texto pode mudar sem aviso. |
| `code` | O código do erro, estável. É ele que o seu código deve tratar. |
| `requestId` | Identificador da chamada. Envie ao suporte ao perguntar sobre uma resposta. |
| `errors` | Só em `validation_failed`: a lista de campos inválidos, cada item com `field` e `message`. |

## Resumo dos códigos

| Código | HTTP | Repetir a chamada? |
|---|---|---|
| [`validation_failed`](#validation_failed) | 400 | Não, corrija a requisição |
| [`token_invalid`](#token_invalid) | 401 | Não, corrija o cabeçalho ou peça um token novo |
| [`token_expired`](#token_expired) | (não é mais emitido) | Veja `token_invalid` |
| [`credential_revoked`](#credential_revoked) | 401 ou 403 | Não, é preciso uma credencial nova |
| [`plan_required`](#plan_required) | 403 | Não, depende do plano da empresa |
| [`access_denied`](#access_denied) | 403 | Não, fale com o suporte |
| [`scope_missing`](#scope_missing) | 403 | Não, falta o escopo na credencial |
| [`method_not_allowed`](#method_not_allowed) | 403 ou 405 | Não, confira o caminho |
| [`not_found`](#not_found) | 404 | Não, confira o id |
| [`rate_limited`](#rate_limited) | 429 | Sim, depois de esperar o `Retry-After` |
| [`internal_error`](#internal_error) | 500 | Sim, com espera crescente |
| [`gateway_error`](#gateway_error) | 5xx | Sim, com espera crescente |
| [`maintenance`](#maintenance) | 503 | Sim, depois da janela |

## validation_failed

**HTTP 400.** Algum parâmetro de consulta é inválido: cursor malformado, `limit` fora de 1 a 100, `status` desconhecido ou data fora do formato `yyyy-MM-dd`.
O campo `errors` lista cada campo com problema.

**O que fazer:** corrija a requisição. Repetir a mesma chamada falha do mesmo jeito. Veja os formatos aceitos em
[Paginação e datas](https://developers.festero.com.br/paginacao.md).

## token_invalid

**HTTP 401.** O cabeçalho `Authorization` está ausente ou malformado, a assinatura do token não é válida ou **o token venceu** (passou dos 60 minutos).

**O que fazer:** envie `Authorization: Bearer <access_token>` com um token emitido pelo endpoint de token do Festero.
Se o token venceu, peça um novo e guarde-o durante toda a validade: não peça um token a cada chamada, o endpoint de
token tem limite de uso. Veja [Autenticação](https://developers.festero.com.br/autenticacao.md).

## token_expired

Este código **não é mais emitido**. Antes, um token vencido recebia `403` com este código; agora recebe `401` com
[`token_invalid`](#token_invalid), que é o que os clientes MCP e OAuth esperam para renovar o token sozinhos. A âncora fica
para quem ainda tem links antigos para esta página.

**O que fazer:** trate qualquer `401` pedindo um token novo (veja [`token_invalid`](#token_invalid)).

## credential_revoked

**HTTP 401 ou 403.** A credencial foi revogada, suspensa ou expirou no Festero, ou ainda está **Ativando** (acabou de ser criada).

**O que fazer:** se a credencial acabou de ser criada, espere o status passar a **Ativa** em **API do Festero**. Nos outros casos, peça ao
administrador da empresa uma credencial nova. Repetir a chamada não resolve.

## plan_required

**HTTP 403.** O plano da empresa não inclui a API. Os planos Premium e Enterprise incluem.

**O que fazer:** a empresa precisa mudar de plano no Festero. Não repita a chamada.

## access_denied

**HTTP 403.** A chamada foi recusada por um motivo que não pode ser divulgado.

**O que fazer:** confira a credencial em **API do Festero** e fale com o suporte informando o `requestId`.

## scope_missing

**HTTP 403.** A credencial não tem o escopo do conjunto de dados que a rota lê. O campo `detail` informa qual escopo falta.

**O que fazer:** crie uma credencial que inclua esse conjunto de dados em **API do Festero**; os escopos de uma credencial
existente não mudam. Veja os escopos em [Autenticação](https://developers.festero.com.br/autenticacao.md#escopos).

## method_not_allowed

**HTTP 403 ou 405.** O método ou o caminho não existe nesta API. A API é somente de leitura. `GET /v1/mcp` responde `405`: o servidor MCP só aceita `POST`.

**O que fazer:** confira o caminho e o método na [Referência interativa](https://developers.festero.com.br/referencia/).

## not_found

**HTTP 404.** O recurso não existe ou não está visível para esta credencial, o que inclui recursos de outra empresa.

**O que fazer:** confira o id. Um recurso excluído no Festero deixa de aparecer.

## rate_limited

**HTTP 429.** O limite do plano por minuto ou a cota do dia foi atingido. A resposta traz o cabeçalho `Retry-After` (60 segundos), e o `detail` diz qual dos dois estourou.

**O que fazer:** espere o tempo do `Retry-After` e diminua o ritmo. Prefira `sales-summary` e `updatedSince` a paginar tudo.
Veja [Limites de uso](https://developers.festero.com.br/limites.md).

## internal_error

**HTTP 500.** Erro inesperado do nosso lado.

**O que fazer:** tente de novo com espera crescente. Se persistir, fale com o suporte informando o `requestId`.

## gateway_error

**HTTP 5xx do gateway** (por exemplo, 504 quando a API leva mais de 29 segundos para responder). A API ficou indisponível ou passou do tempo limite.

**O que fazer:** tente de novo com espera crescente. Se repetir, reduza a consulta (`limit` menor, período mais curto).

## maintenance

**HTTP 503.** Código reservado para janelas de manutenção anunciadas. Nenhuma resposta atual da API usa este código.

**O que fazer:** se um dia aparecer, tente de novo depois da janela.

## Webhooks

O contrato de entrega dos webhooks (cabeçalhos, assinatura, reentregas e limites) está em [Webhooks](https://developers.festero.com.br/webhooks.md) e em
[Verificar a assinatura](https://developers.festero.com.br/webhooks/assinatura.md).