Fehler
Das Fehlerformat, alle Codes und bei welchen sich ein erneuter Versuch lohnt.
Jeder Fehler hat dieselbe Struktur:
{
"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.reasonistrevision_conflict,details.current_revisionenthält die zu lesende Revision unddetails.pathsfü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.blockersaus. - Ein Tariflimit, zum Beispiel zu viele Entwürfe oder eine Domain, die den Tarif überschreitet. Die Nachricht nennt das Limit, und
action_urlverweist 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.