# Erros e limites da API

> O formato JSON de cada erro da API REST da Endless, o campo data.code para decidir o que fazer e os cabeçalhos RateLimit de 1.000 requisições por minuto.

Source: https://endless.app/pt/docs/reference/api-errors

Todo erro da API REST da Endless em `https://api.endless.app` retorna JSON em um único formato, e toda resposta informa quantas requisições ainda restam. O versionamento tem [página própria](/pt/docs/reference/api-versioning).

## O formato de um erro

```json
{
  "code": "FORBIDDEN",
  "status": 403,
  "message": "Your role does not have permission to do this",
  "data": { "code": "permission_denied" }
}
```

| Campo                | O que é                                                                               |
| -------------------- | ------------------------------------------------------------------------------------- |
| `code`               | O status HTTP como palavra: `BAD_REQUEST`, `UNAUTHORIZED`, `NOT_FOUND`, …             |
| `status`             | O status HTTP como número                                                             |
| `message`            | Uma frase para uma pessoa. Pode mudar de redação, então não compare com ela           |
| `data.code`          | O motivo legível por máquina, em `snake_case`. **É o campo para decidir o que fazer** |
| `data.hint`          | Quando presente, o passo que resolve                                                  |
| `data.documentation` | Quando presente, um link para a referência da API                                     |

O schema `Error` no [documento OpenAPI](https://api.endless.app/openapi.json) lista cada `data.code`, e cada operação na [referência da API](/docs/api) lista seus status.

## Códigos comuns

| Status | `data.code`                                      | O que fazer                                                     |
| ------ | ------------------------------------------------ | --------------------------------------------------------------- |
| 400    | (validação)                                      | `message` diz o campo e a regra que ele violou                  |
| 400    | `unsupported_api_version`                        | Veja [Versões da API](/pt/docs/reference/api-versioning)        |
| 401    | `missing_token`                                  | Envie `Authorization: Bearer <token>`                           |
| 401    | `invalid_token`                                  | O token não foi verificado ou expirou. Obtenha um novo          |
| 402    | `insufficient_credits`, `exceeds_spending_limit` | O espaço de trabalho ou quem chama não pode pagar a chamada     |
| 403    | `permission_denied`, `forbidden`                 | A função ou o acesso de quem chama não permite                  |
| 404    | `not_found`, `organization_not_found`, …         | O recurso não existe, ou quem chama não pode abri-lo            |
| 404    | `route_not_found`                                | Nenhuma operação corresponde ao caminho (nunca uma página HTML) |
| 404    | `invalid_path_parameter`                         | Um id no caminho não pode nomear um recurso                     |
| 429    | `rate_limited`                                   | Espere os segundos de `retry_after` e tente de novo             |

## Limites de requisições

* **Limite:** 1.000 requisições a cada 60 segundos por quem chama, em uma política chamada `default`. Um único contador por quem chama em todos os servidores.
* **Janela fixa:** ela reinicia de uma vez, então controle o ritmo por `RateLimit-Remaining`, não supondo um ritmo constante.
* **Créditos são separados:** ficar sem saldo ou sem limite de gastos retorna `402`, não `429`.

Toda resposta da API, com sucesso ou erro, traz o contador em dois formatos (navegadores também podem lê-los):

```http
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=997;t=42
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42
```

`r` / `RateLimit-Remaining` são as requisições restantes; `t` / `RateLimit-Reset` são os segundos até reiniciar. Acima do limite, a API responde `429` com um cabeçalho `Retry-After` e os mesmos segundos no corpo:

```json
{
  "code": "TOO_MANY_REQUESTS",
  "status": 429,
  "message": "Too many requests.",
  "data": {
    "code": "rate_limited",
    "hint": "Wait 42s, then retry. Every response carries RateLimit headers — read them to pace yourself before you are refused.",
    "documentation": "https://endless.app/docs/api"
  },
  "retry_after": 42
}
```

## Fontes legíveis por máquina

* [Índice da API](https://api.endless.app/): seus objetos `rate_limit` e `errors` descrevem esta política.
* [Documento OpenAPI](https://api.endless.app/openapi.json): o schema `Error` em cada resposta de erro.
* O [servidor MCP](/pt/docs/connect) tem limite próprio: 60 chamadas de ferramentas por minuto por conta.