--- title: "Fehler" description: "Das Fehlerformat, alle Codes und bei welchen sich ein erneuter Versuch lohnt." canonical: "https://atelier201.com/docs/de/api/errors" updated: "2026-11-06" --- # Fehler Jeder Fehler hat dieselbe Struktur: ```json { "error": { "type": "not_found_error", "code": "resource_not_found", "message": "This site does not exist.", "docs_url": "https://atelier201.com/docs/api/errors#resource_not_found" }, "request_id": "req_01K9X7" } ``` **Werten Sie `code` aus, niemals `message`.** Codes sind verbindlich. Nachrichten sind für Menschen geschrieben und werden laufend verbessert. Einige Fehler enthalten zusätzlich ein `details`-Objekt mit den nötigen Informationen, etwa der aktuellen Revision nach einem Schreibkonflikt. ## Wann erneut versuchen? | Status | Erneut versuchen? | | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 429 | Ja, nach `Retry-After`. | | 5xx | Nur bei einer idempotenten Anfrage (GET, PUT, DELETE). Ein POST, der mit einem 5xx fehlschlägt, wurde möglicherweise bereits ausgeführt. Lesen Sie die Ressource zuerst erneut aus. | | 4xx | Nein. Die Anfrage ist fehlerhaft und wird es beim nächsten Versuch wieder sein. | ## Alle Codes ### authentication\_required `authentication_error` · HTTP 401 Es wurden keine Anmeldedaten gesendet. Fügen Sie einen `Authorization: Bearer`-Header hinzu. ### invalid\_api\_key `authentication_error` · HTTP 401 Die Anmeldedaten werden nicht erkannt. Sie gehören möglicherweise zu einem Arbeitsbereich, der nicht mehr existiert. ### api\_key\_expired `authentication_error` · HTTP 401 Der Schlüssel ist abgelaufen. Erstellen Sie einen neuen. ### api\_key\_revoked `authentication_error` · HTTP 401 Der Schlüssel wurde widerrufen. Das ist dauerhaft. ### insufficient\_scope `permission_error` · HTTP 403 Die Anmeldedaten sind gültig, aber ihnen wurde nicht der für diesen Endpunkt erforderliche Scope erteilt. Die Nachricht nennt den Scope. Stellen Sie die Anmeldedaten erneut aus. Der Scope kann nicht nachträglich erweitert werden. ### feature\_not\_available `permission_error` · HTTP 403 Dieser Tarif umfasst die Funktion nicht. Beim Veröffentlichen eines Entwurfs wird dies so angezeigt: `details.blockers` enthält `plan_required`, und `action_url` öffnet den Tarif der Site. ### admin\_required `permission_error` · HTTP 403 Diese Aktion ist auf Admins des Arbeitsbereichs beschränkt: Veröffentlichen, Zurücksetzen, eine Site offline nehmen, eine Site löschen und ihre Domains ändern. ### invalid\_request `invalid_request_error` · HTTP 400 Der Body oder die Abfrage war ungültig. Die Nachricht nennt das betreffende Feld. ### unknown\_field `invalid_request_error` · HTTP 400 Es wurde ein Feld gesendet, das dieser Endpunkt nicht akzeptiert. Eingaben werden absichtlich strikt geprüft: Ein stillschweigend ignoriertes Feld könnte erst viel später zum Problem werden. ### invalid\_parameter `invalid_request_error` · HTTP 400 Ein Parameter hatte ein falsches Format, meist eine fehlerhafte ID. ### invalid\_cursor `invalid_request_error` · HTTP 400 Der Paginierungs-Cursor wurde nicht von uns ausgegeben. Starten Sie die Auflistung erneut. ### request\_too\_large `invalid_request_error` · HTTP 413 Der Body hat die feste Größenbegrenzung überschritten. ### resource\_not\_found `not_found_error` · HTTP 404 Ein solches Objekt gibt es in DIESEM Arbeitsbereich nicht. Auch für eine Ressource aus einem anderen Arbeitsbereich wird dieser Fehler zurückgegeben, und zwar absichtlich: Eine Unterscheidung würde verraten, welche IDs existieren. ### conflict `conflict_error` · HTTP 409 Die Ressource existiert und die Anfrage ist korrekt aufgebaut, aber ihr aktueller Zustand verhindert die Aktion. Anders als bei einem 400 kann sie später erfolgreich sein. Häufige Ursachen: - Ein Schreibkonflikt. Jemand hat eine Datei geändert, seit Sie sie gelesen haben. `details.reason` ist `revision_conflict`, `details.current_revision` enthält die zu lesende Revision und `details.paths` führt jede Datei mit dem erwarteten und dem gefundenen Hash auf. - Eine Veröffentlichung auf Grundlage einer veralteten Prüfung oder ein Build, der nicht live geschaltet werden kann. Prüfen Sie erneut und lesen Sie `details.blockers` aus. - Ein Tariflimit, zum Beispiel zu viele Entwürfe oder eine Domain, die den Tarif überschreitet. Die Nachricht nennt das Limit, und `action_url` verweist auf die Seite, auf der Sie es aufheben können. ### result\_not\_ready `conflict_error` · HTTP 409 Der Vorgang ist noch nicht abgeschlossen, zum Beispiel weil eine Site noch erstellt wird. Warten Sie einige Sekunden, statt es sofort erneut zu versuchen. ### idempotency\_key\_reused `conflict_error` · HTTP 409 Der `Idempotency-Key`, den Sie an einen Endpunkt gesendet haben, der einen solchen Schlüssel akzeptiert, wurde in diesem Arbeitsbereich bereits für eine andere Anfrage verwendet. Es wurde nichts ausgeführt. Verwenden Sie für einen neuen Vorgang einen neuen Schlüssel. Wird dieselbe Anfrage mit demselben Schlüssel wiederholt, wird stattdessen die erste Antwort zurückgegeben. ### insufficient\_credits `invalid_request_error` · HTTP 402 Nicht genügend Credits. **Brechen Sie ab und informieren Sie eine zuständige Person**. Ein erneuter Versuch hilft nicht. ### request\_too\_large\_for\_plan `invalid_request_error` · HTTP 422 Der Body liegt unter der festen Größenbegrenzung, überschreitet aber das für diesen Tarif zulässige Limit. ### result\_expired `not_found_error` · HTTP 410 Das Ergebnis wurde gemäß der Aufbewahrungsrichtlinie gelöscht. Es lässt sich nicht wiederherstellen. ### rate\_limited `rate_limit_error` · HTTP 429 Zu viele Anfragen. Warten Sie `Retry-After` ab, bevor Sie es erneut versuchen. Dieselbe Wartezeit steht als Daten im Body: `details.retry_after_seconds` und `details.retry_at` (ein ISO-Datum). Sie ist auch in MCP-Toolfehlern und in der JSON-Ausgabe der CLI enthalten. ### internal\_error `api_error` · HTTP 500 Auf unserer Seite ist ein Fehler aufgetreten. Geben Sie die `request_id` an. ### service\_unavailable `api_error` · HTTP 503 Ein abhängiger Dienst ist ausgefallen oder wird gewartet. Versuchen Sie es nach einer Wartezeit erneut.