# Errores y límites de la API

> La forma JSON de cada error de la API REST de Endless, el campo data.code con el motivo y los encabezados RateLimit de 1.000 solicitudes por minuto.

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

Cada error de la API REST de Endless en `https://api.endless.app` devuelve JSON con una sola forma, y cada respuesta indica cuántas solicitudes te quedan. Las versiones tienen [su propia página](/es/docs/reference/api-versioning).

## La forma de un error

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

| Campo                | Qué es                                                                               |
| -------------------- | ------------------------------------------------------------------------------------ |
| `code`               | El estado HTTP como palabra: `BAD_REQUEST`, `UNAUTHORIZED`, `NOT_FOUND`, …           |
| `status`             | El estado HTTP como número                                                           |
| `message`            | Una frase para una persona. Puede cambiar de redacción, así que no compares con ella |
| `data.code`          | El motivo legible por máquina, en `snake_case`. **Es el campo con el que decidir**   |
| `data.hint`          | Si aparece, el paso que lo resuelve                                                  |
| `data.documentation` | Si aparece, un enlace a la referencia de la API                                      |

El esquema `Error` del [documento OpenAPI](https://api.endless.app/openapi.json) enumera cada `data.code`, y cada operación de la [referencia de la API](/docs/api) enumera sus estados.

## Códigos frecuentes

| Estado | `data.code`                                      | Qué hacer                                                         |
| ------ | ------------------------------------------------ | ----------------------------------------------------------------- |
| 400    | (validación)                                     | `message` nombra el campo y la regla que no cumplió               |
| 400    | `unsupported_api_version`                        | Consulta [Versiones de la API](/es/docs/reference/api-versioning) |
| 401    | `missing_token`                                  | Envía `Authorization: Bearer <token>`                             |
| 401    | `invalid_token`                                  | El token no se verificó o venció. Obtén uno nuevo                 |
| 402    | `insufficient_credits`, `exceeds_spending_limit` | El espacio de trabajo o quien llama no puede pagar la llamada     |
| 403    | `permission_denied`, `forbidden`                 | El rol o el acceso de quien llama no lo permite                   |
| 404    | `not_found`, `organization_not_found`, …         | El recurso no existe, o quien llama no puede abrirlo              |
| 404    | `route_not_found`                                | Ninguna operación coincide con la ruta (nunca una página HTML)    |
| 404    | `invalid_path_parameter`                         | Un id de la ruta no puede nombrar un recurso                      |
| 429    | `rate_limited`                                   | Espera los segundos de `retry_after` y reintenta                  |

## Límites de solicitudes

* **Límite:** 1.000 solicitudes cada 60 segundos por quien llama, en una política llamada `default`. Un solo contador por quien llama en todos los servidores.
* **Ventana fija:** se reinicia de golpe, así que regula el ritmo con `RateLimit-Remaining`, no suponiendo un ritmo parejo.
* **Los créditos van aparte:** quedarse sin saldo o sin límite de gasto devuelve `402`, no `429`.

Cada respuesta de la API, con éxito o con error, trae el contador en dos formatos (los navegadores también pueden leerlos):

```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` son las solicitudes que quedan; `t` / `RateLimit-Reset` son los segundos hasta el reinicio. Al pasarte del límite, la API responde `429` con un encabezado `Retry-After` y los mismos segundos en el cuerpo:

```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
}
```

## Fuentes legibles por máquina

* [Índice de la API](https://api.endless.app/): sus objetos `rate_limit` y `errors` describen esta política.
* [Documento OpenAPI](https://api.endless.app/openapi.json): el esquema `Error` en cada respuesta de error.
* El [servidor MCP](/es/docs/connect) tiene su propio límite: 60 llamadas a herramientas por minuto por cuenta.