API-Fehler und Rate Limits
Das JSON-Format, in dem jeder Fehler der Endless-REST-API zurückkommt, das Feld data.code zum Verzweigen und die RateLimit-Header für 1.000 Anfragen pro Minute.
Jeder Fehler der Endless-REST-API unter https://api.endless.app liefert JSON in einem einzigen Format, und jede Antwort meldet dein verbleibendes Anfragebudget. Versionierung hat eine eigene Seite.
Das Fehlerformat
{
"code": "FORBIDDEN",
"status": 403,
"message": "Your role does not have permission to do this",
"data": { "code": "permission_denied" }
}| Feld | Was es ist |
|---|---|
code | Der HTTP-Status als Wort: BAD_REQUEST, UNAUTHORIZED, NOT_FOUND, … |
status | Der HTTP-Status als Zahl |
message | Ein Satz für Menschen. Er kann umformuliert werden, vergleiche also nicht damit |
data.code | Der maschinenlesbare Grund in snake_case. Das ist das Feld, nach dem du verzweigst |
data.hint | Falls vorhanden, der Schritt, der das Problem löst |
data.documentation | Falls vorhanden, ein Link zur API-Referenz |
Das Schema Error im OpenAPI-Dokument listet jeden data.code, und jede Operation in der API-Referenz listet ihre Status.
Häufige Codes
| Status | data.code | Was zu tun ist |
|---|---|---|
| 400 | (Validierung) | message nennt das Feld und die verletzte Regel |
| 400 | unsupported_api_version | Siehe API-Versionierung |
| 401 | missing_token | Sende Authorization: Bearer <token> |
| 401 | invalid_token | Der Token wurde nicht verifiziert oder ist abgelaufen. Hole einen neuen |
| 402 | insufficient_credits, exceeds_spending_limit | Der Workspace oder der Aufrufer kann diesen Aufruf nicht bezahlen |
| 403 | permission_denied, forbidden | Die Rolle oder der Zugriff des Aufrufers erlaubt es nicht |
| 404 | not_found, organization_not_found, … | Die Ressource existiert nicht, oder der Aufrufer kann sie nicht öffnen |
| 404 | route_not_found | Keine Operation passt zum Pfad (nie eine HTML-Seite) |
| 404 | invalid_path_parameter | Eine ID im Pfad kann keine Ressource bezeichnen |
| 429 | rate_limited | Warte die Sekunden aus retry_after ab und versuche es dann erneut |
Rate Limits
- Limit: 1.000 Anfragen pro 60 Sekunden und Aufrufer, in einer Policy namens
default. Ein Zähler pro Aufrufer über alle Server hinweg. - Festes Zeitfenster: Es wird auf einmal zurückgesetzt, richte dein Tempo also nach
RateLimit-Remainingund nicht nach einer angenommenen gleichmäßigen Rate. - Credits sind getrennt: Ist das Guthaben oder das Ausgabenlimit aufgebraucht, kommt
402, nicht429.
Jede API-Antwort, ob Erfolg oder Fehler, trägt den Zähler in zwei Schreibweisen (Browser können sie ebenfalls lesen):
RateLimit-Policy: "default";q=1000;w=60
RateLimit: "default";r=997;t=42
RateLimit-Limit: 1000
RateLimit-Remaining: 997
RateLimit-Reset: 42r / RateLimit-Remaining sind die verbleibenden Anfragen; t / RateLimit-Reset sind die Sekunden bis zum Zurücksetzen. Über dem Limit antwortet die API mit 429, einem Retry-After-Header und denselben Sekunden im Body:
{
"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
}Maschinenlesbare Quellen
- API-Index: Seine Objekte
rate_limitunderrorsbeschreiben diese Policy. - OpenAPI-Dokument: das Schema
Errorin jeder Fehlerantwort. - Der MCP-Server hat ein eigenes Limit: 60 Tool-Aufrufe pro Minute und Konto.