Fehler
Jede Fehlerantwort der Developer-API hat denselben Aufbau. Der Code sagt maschinenlesbar, was schiefging, die Meldung sagt es dir. Das gilt auch für unbekannte Pfade und falsche Methoden: Sie antworten mit 404 oder 405 im selben Umschlag.
Fehlerumschlag
Der Körper jeder Fehlerantwort ist { code, message, requestId, errors?, scope? }. Fehlt errors oder scope, steht der Schlüssel nicht im JSON, er ist nie null.
| Feld | Inhalt |
|---|---|
| code | Maschinenlesbarer Code aus den Tabellen unten. Richte deine Fallunterscheidung danach. |
| message | Erklärung für Menschen. Zeige sie an, werte sie aber nicht maschinell aus. |
| requestId | Id des Aufrufs, gleich dem Header X-Request-Id. Nenne sie dem Support, wenn du Hilfe brauchst. |
| errors | Nur bei VALIDATION_ERROR: je Feld eine Liste von Meldungen. |
| scope | Nur bei INSUFFICIENT_SCOPE: das fehlende Recht. |
Du kannst einen eigenen Header X-Request-Id mitschicken. Die Antwort trägt immer eine Id: deinen Wert, wenn er höchstens 64 Zeichen aus A-Z a-z 0-9 - . _ hat, sonst eine neue von Zenit.
Beispiel VALIDATION_ERROR mit errors
{
"code": "VALIDATION_ERROR",
"message": "Die Eingabe ist ungültig.",
"requestId": "8d41b6c07e2f4a95b3c1e60d7f9a2b84",
"errors": {
"limit": ["Der Wert muss zwischen 1 und 100 liegen."]
}
}Allgemeine Codes
Diese Codes können bei jedem Endpunkt der Developer-API vorkommen.
| Code | Status | Ursache und nächster Schritt |
|---|---|---|
| TOKEN_INVALID | 401 | Das Token fehlt, ist falsch, abgelaufen oder widerrufen, das Konto ist gesperrt oder die IP-Adresse ist nicht erlaubt. Die API unterscheidet die Fälle nicht. Prüfe das Token in deinem Profil und lege bei Bedarf ein neues an. |
| INSUFFICIENT_SCOPE | 403 | Dem Token oder der Installation des Bots fehlt das Recht, das der Aufruf braucht. Das Feld scope nennt es. Nutze ein Token mit diesem Recht. |
| FORBIDDEN | 403 | Dir fehlt die Freigabe für die Aktion: Als Mitbenutzer brauchst du das passende Freigabe-Recht auf dem Server, Aktionen nur für Besitzer sind dir verwehrt, und ein Zugriffstoken darf keine Bot-Endpunkte aufrufen. Bitte den Besitzer um die Freigabe oder nutze das passende Token. |
| NOT_FOUND | 404 | Das Objekt gibt es nicht, oder du darfst es nicht sehen. Die API verrät den Unterschied nicht. Dasselbe gilt für einen unbekannten Pfad, eine unbekannte Version und eine Id, die keine gültige GUID ist. Prüfe Pfad, Version, Id und deine Freigabe. |
| METHOD_NOT_ALLOWED | 405 | Der Endpunkt kennt diese HTTP-Methode nicht. Der Header Allow nennt die erlaubten Methoden. Nutze eine davon. |
| VALIDATION_ERROR | 400 | Die Eingabe ist ungültig, zum Beispiel ein limit außerhalb von 1 bis 100 oder ein ungültiger Cursor. Das Feld errors nennt je Feld die Meldungen. Korrigiere die Eingabe. |
| CONFLICT | 409 | Der Zustand erlaubt die Aktion nicht, und kein spezifischerer Code passt. Lies die Meldung, prüfe den Zustand und versuche es danach erneut. |
| IDEMPOTENCY_IN_PROGRESS | 409 | Ein Aufruf mit demselben Idempotency-Key läuft noch. Warte kurz und sende denselben Aufruf mit demselben Key erneut. |
| IDEMPOTENCY_KEY_REUSED | 422 | Du hast denselben Idempotency-Key mit einem anderen Aufruf benutzt. Erzeuge für jede neue Aktion einen neuen Key. |
| RATE_LIMITED | 429 | Du hast das Limit erreicht. Warte die Zeit ab, die der Header Retry-After nennt. |
| INTERNAL_ERROR | 500 | Auf Seiten von Zenit ist etwas schiefgelaufen. Versuche es später erneut. Bleibt der Fehler, nenne dem Support die requestId. |
| DEVELOPER_FEATURE_UNAVAILABLE | 409 | Die Funktion ist auf der Plattform gerade nicht verfügbar. Versuche es später erneut. |
Codes für Server und Git
Diese Codes kommen beim Starten, Stoppen, Senden von Befehlen und beim Git-Deploy vor.
| Code | Status | Ursache und nächster Schritt |
|---|---|---|
| SERVER_NOT_READY | 400 oder 409 | Der Zustand des Servers erlaubt die Aktion nicht, zum Beispiel während der Einrichtung. Warte, bis der Server bereit ist, und versuche es später mit einem neuen Idempotency-Key erneut. |
| CAPACITY_UNAVAILABLE | 409 | Der Start geht gerade nicht, weil der Flex-Pool voll ist. Versuche den Start später mit einem neuen Idempotency-Key erneut. |
| START_BLOCKED | 409 | Der Start ist gesperrt, zum Beispiel durch das Flex-Monatslimit oder eine Zahlungssperre. Der Besitzer muss im Kundenbereich handeln. |
| GIT_DEPLOY_NOT_ALLOWED | 409 | Das Paket des Servers ist für Git-Deployments nicht freigegeben. Lade den Code im Bereich Dateien des Servers hoch oder wende dich an den Support. |
Codes der Verwaltung im Kundenbereich
Diese Codes kommen beim Anlegen von Tokens und Bots und beim Installieren von Bots im Kundenbereich vor, nicht bei der Developer-API.
| Code | Status | Ursache und nächster Schritt |
|---|---|---|
| DEVELOPER_TOKEN_LIMIT_REACHED | 409 | Du hast 50 aktive Tokens. Widerrufe eines, das du nicht mehr brauchst. |
| BOT_LIMIT_REACHED | 409 | Du hast 10 Bots. Lösche einen, den du nicht mehr brauchst. |
| BOT_SLUG_TAKEN | 409 | Die Kennung des Bots ist schon vergeben. Wähle eine andere. Reservierte Kennungen mit dem Präfix zenit antworten mit 400 VALIDATION_ERROR. |
| BOT_ALREADY_INSTALLED | 409 | Der Bot ist auf diesem Server schon installiert. Ändere die bestehende Installation. |
| BOT_NOT_ACTIVE | 409 | Der Bot ist deaktiviert oder gesperrt. Aktiviere ihn oder wende dich an den Support. |
| TWOFA_REQUIRED | 403 | Die Aktion verlangt den zweiten Faktor. Bestätige ihn und wiederhole die Aktion. |
Fehler beim Starten und Stoppen
POST /servers/{id}/power und POST /servers/{id}/commands laufen über dieselbe Steuerung wie der Kundenbereich. Deren Codes bildet die Developer-API so ab:
| Code im Kundenbereich | Antwort der Developer-API |
|---|---|
| SERVER_NOT_FOUND | 404 NOT_FOUND |
| INVALID_ACTION | 400 VALIDATION_ERROR |
| SERVER_NOT_READY | unverändert: 400 oder 409 SERVER_NOT_READY |
| FLEX_POOL_AT_CAPACITY | 409 CAPACITY_UNAVAILABLE |
| FLEX_BUDGET_REACHED | 409 START_BLOCKED |
| FLEX_PAYMENT_BLOCKED | 409 START_BLOCKED |
| DEVELOPER_FEATURE_UNAVAILABLE | unverändert: 409 DEVELOPER_FEATURE_UNAVAILABLE |
Trägt ein Fehler keinen oder einen unbekannten Code, setzt die API den Standardcode zur Art des Fehlers:
- ungültige Eingabe:
VALIDATION_ERROR - nicht gefunden:
NOT_FOUND - Konflikt:
CONFLICT - nicht angemeldet:
TOKEN_INVALID - nicht erlaubt:
FORBIDDEN - Limit erreicht:
RATE_LIMITED
Fehler im Client behandeln
- Entscheide nach
code, nicht nach dem Text der Meldung. - Kennt dein Client einen Code nicht, behandle die Antwort nach ihrem HTTP-Status. Es können neue Codes und Felder dazukommen, siehe Versionierung.
- Bei 429 und 5xx kannst du den Aufruf wiederholen, bei POST mit demselben Idempotency-Key. Beachte bei 429 den Header
Retry-After, siehe Rate-Limits.