Erreurs et limites de l'API
La forme JSON de chaque erreur de l'API REST d'Endless, le champ data.code qui en donne la raison et les en-têtes RateLimit pour 1 000 requêtes par minute.
Chaque erreur de l'API REST d'Endless sur https://api.endless.app renvoie du JSON sous une seule forme, et chaque réponse indique combien de requêtes il vous reste. Le versionnage a sa propre page.
La forme d'une erreur
{
"code": "FORBIDDEN",
"status": 403,
"message": "Your role does not have permission to do this",
"data": { "code": "permission_denied" }
}| Champ | Ce que c'est |
|---|---|
code | Le statut HTTP sous forme de mot : BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, … |
status | Le statut HTTP sous forme de nombre |
message | Une phrase destinée à une personne. Sa formulation peut changer, ne vous appuyez donc pas dessus |
data.code | La raison lisible par une machine, en snake_case. C'est le champ sur lequel baser votre logique |
data.hint | Lorsqu'elle est présente, l'étape qui résout le problème |
data.documentation | Lorsqu'il est présent, un lien vers la référence de l'API |
Le schéma Error du document OpenAPI liste chaque data.code, et chaque opération de la référence de l'API liste ses statuts.
Codes courants
| Statut | data.code | Que faire |
|---|---|---|
| 400 | (validation) | message nomme le champ et la règle enfreinte |
| 400 | unsupported_api_version | Voir Versionnage de l'API |
| 401 | missing_token | Envoyez Authorization: Bearer <token> |
| 401 | invalid_token | Le jeton n'a pas été validé ou a expiré. Obtenez-en un nouveau |
| 402 | insufficient_credits, exceeds_spending_limit | L'espace de travail ou l'appelant ne peut pas payer cet appel |
| 403 | permission_denied, forbidden | Le rôle ou l'accès de l'appelant ne l'autorise pas |
| 404 | not_found, organization_not_found, … | La ressource n'existe pas, ou l'appelant ne peut pas l'ouvrir |
| 404 | route_not_found | Aucune opération ne correspond au chemin (jamais une page HTML) |
| 404 | invalid_path_parameter | Un identifiant du chemin ne peut désigner aucune ressource |
| 429 | rate_limited | Attendez le nombre de secondes indiqué dans retry_after, puis réessayez |
Limites de requêtes
- Limite : 1 000 requêtes par période de 60 secondes et par appelant, dans une politique nommée
default. Un seul compteur par appelant sur tous les serveurs. - Fenêtre fixe : elle se réinitialise d'un coup, réglez donc votre rythme sur
RateLimit-Remaining, pas sur un débit supposé régulier. - Les crédits sont à part : un solde épuisé ou un plafond de dépenses atteint renvoie
402, pas429.
Chaque réponse de l'API, réussie ou non, porte le compteur sous deux formes (les navigateurs peuvent aussi les lire) :
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=997;t=42
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42r / RateLimit-Remaining correspondent aux requêtes restantes ; t / RateLimit-Reset aux secondes avant la réinitialisation. Au-delà de la limite, l'API renvoie 429 avec un en-tête Retry-After et le même nombre de secondes dans le corps :
{
"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
}Sources lisibles par une machine
- Index de l'API : ses objets
rate_limiteterrorsdécrivent cette politique. - Document OpenAPI : le schéma
Errorde chaque réponse d'erreur. - Le serveur MCP a sa propre limite : 60 appels d'outils par minute et par compte.