# 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.

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

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](/reference/api-versioning).

## Das Fehlerformat

```json
{
  "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](https://api.endless.app/openapi.json) listet jeden `data.code`, und jede Operation in der [API-Referenz](/docs/api) 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](/reference/api-versioning)                    |
| 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-Remaining` und nicht nach einer angenommenen gleichmäßigen Rate.
- **Credits sind getrennt:** Ist das Guthaben oder das Ausgabenlimit aufgebraucht, kommt `402`, nicht `429`.

Jede API-Antwort, ob Erfolg oder Fehler, trägt den Zähler in zwei Schreibweisen (Browser können sie ebenfalls lesen):

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

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

## Maschinenlesbare Quellen

- [API-Index](https://api.endless.app/): Seine Objekte `rate_limit` und `errors` beschreiben diese Policy.
- [OpenAPI-Dokument](https://api.endless.app/openapi.json): das Schema `Error` in jeder Fehlerantwort.
- Der [MCP-Server](/connect) hat ein eigenes Limit: 60 Tool-Aufrufe pro Minute und Konto.