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.
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.
La forma de un error
{
"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 enumera cada data.code, y cada operación de la referencia de la 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 |
| 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, no429.
Cada respuesta de la API, con éxito o con error, trae el contador en dos formatos (los navegadores también pueden leerlos):
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=997;t=42
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42r / 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:
{
"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: sus objetos
rate_limityerrorsdescriben esta política. - Documento OpenAPI: el esquema
Erroren cada respuesta de error. - El servidor MCP tiene su propio límite: 60 llamadas a herramientas por minuto por cuenta.