API-Fehler
API-Fehler einordnen: Anfrage korrigieren oder wiederholen und Zahlungen sowie Sendungen ohne Duplikate erneut versuchen.
Auf dieser Seite
Schlägt eine Anfrage fehl, prüfen Sie zuerst den HTTP-Code: 401 weist etwa auf ein Zugriffsproblem hin, 429 auf zu viele Anfragen. Das Feld error nennt den Grund genauer. Erfolgreiche Antworten enthalten die Daten direkt, ohne gemeinsame Hülle.
Fehlerformat
Bei Fehlern gibt der Server ein JSON-Objekt mit dem Textfeld error zurück:
{"error":"reaction not found"}
Richten Sie die Programmlogik primär nach dem HTTP-Code aus; den error-Text verwenden Sie für Logs und Hinweise.
Statuscodes
| HTTP-Code | Bedeutung |
|---|---|
200 OK | Anfrage erfolgreich; Antwort enthält Daten. |
201 Created | Neue Ressource angelegt, bei manchen POST-Endpoints. |
204 No Content | Erfolg ohne Antwortkörper, bei manchen Löschvorgängen. |
400 Bad Request | Ungültiger Anfragekörper oder Parameter. |
401 Unauthorized | Token fehlt, ist ungültig oder abgelaufen; oder die Route ist per PAT nicht zugänglich. |
402 Payment Required | Tarif oder Quote reicht nicht, beispielsweise für Premium-Medienspeicher. |
403 Forbidden | Benötigter Scope fehlt oder Tokeninhaber hat nicht das nötige Kontobereichsrecht (missing cabinet right, siehe Kontobereich des Tokens). |
404 Not Found | Ressource fehlt oder gehört Ihnen nicht. |
409 Conflict | Zustandskonflikt, etwa ein doppelter eindeutiger Wert. Bei Idempotency-Key kann es auch bedeuten: dieselbe Operation läuft bereits. |
413 Payload Too Large | Anfragekörper zu groß. Bei Anfragen mit Idempotency-Key gilt ein eigener niedrigerer Grenzwert von 64 KiB. |
422 Unprocessable Entity | Syntaktisch gültige Anfrage verletzt fachliche Regeln. Bei Idempotency-Key kann es auch heißen: gleicher Schlüssel, anderer Körper. |
429 Too Many Requests | Anfragelimit überschritten, siehe Limits. |
500 Internal Server Error | Interner Fehler; später erneut versuchen. |
Fehler behandeln
Behandeln Sie 2xx als Erfolg. Bei 401 oder 403 prüfen Sie Token, Scopes und Kontobereichsrechte. Bei 429 und 5xx ist exponentiell verzögertes Wiederholen sinnvoll.
Ein 4xx außer 429 verlangt normalerweise eine Korrektur statt unveränderter Wiederholung. Ausnahme: 409 bei einer Anfrage mit Idempotency-Key heißt „dieselbe Operation läuft gerade“. Brechen Sie sie nicht als fehlgeschlagen ab, denn etwa Zahlung oder Broadcast kann noch laufen. Warten Sie gemäß Retry-After und wiederholen Sie mit demselben Schlüssel.
Geldoperationen wiederholen: Idempotency-Key
Der Schlüssel muss eine kanonische UUID in Kleinbuchstaben mit Bindestrichen sein, etwa 9b1f0d4c-2f6a-4a5f-9a3f-1f2f3a4b5c6d. Andere Schreibweisen werden mit 400 abgelehnt.
Geltungsbereich
Der Header ist optional, wird aber bei Vorgängen berücksichtigt, deren Wiederholung Geld kosten oder Massenversand starten kann:
POST /api/billing/topup: Guthaben aufladen;POST /api/billing/subscribe: Abonnement abschließen;POST /api/bots/{botID}/reactions/{reactionID}/broadcast: Broadcast starten.
Bei zwei Nachrichtensendungen durch Mitarbeiter ist er dagegen Pflicht; ohne ihn folgt 400:
POST /api/bots/{botID}/users/{userID}/dialog/messages;POST /api/bots/{botID}/support/dialogs/{subscriberID}/templates.
Andere Routen ignorieren den Header. Verlassen Sie sich dort nicht auf ihn als allgemeinen Duplikatschutz: Eine Wiederholung ist eine zweite Anfrage.
Antworten des Servers
- Gleicher Schlüssel und Körper, Operation abgeschlossen: Der Server gibt die gespeicherte Antwort des ersten Versuchs zurück, mit demselben Status und Körper plus
Idempotent-Replay: true. Die Operation läuft einmal. Der Eintrag bleibt eine Woche. - Gleicher Schlüssel, Operation läuft noch:
409plusRetry-After. Wiederholen Sie nach der angegebenen Pause mit demselben Schlüssel; ein neuer Schlüssel könnte eine zweite Abbuchung verursachen. - Gleicher Schlüssel, anderer Körper:
422. Der Server kann nicht wissen, welche Operation beabsichtigt war. Verwenden Sie für die andere Operation einen neuen Schlüssel. - Körper über 64 KiB:
413. Diese Vorgänge brauchen kleine Anfragen; ein so großer Körper deutet auf einen Client-Fehler hin.
Einige Antworten werden bewusst nicht unter dem Schlüssel gespeichert: 5xx, 408, 425 und 429. Sie bedeuten, dass die Anfrage nicht ausgeführt wurde. Eine Wiederholung mit demselben Schlüssel kann deshalb die Arbeit nachholen. Würden die Ablehnungen eine Woche gespeichert, könnte die Operation unter diesem Schlüssel nie abgeschlossen werden.
Praktischer Ablauf
- Erzeugen Sie die UUID vor dem ersten Versuch und speichern Sie sie bei der Aufgabe.
- Senden Sie die Anfrage mit diesem Schlüssel.
- Bei Verbindungsabbruch, Timeout,
5xxoder429wiederholen Sie denselben Schlüssel. - Bei
409warten SieRetry-Afterab und wiederholen mit demselben Schlüssel. - Nur für eine tatsächlich neue Operation erzeugen Sie einen neuen Schlüssel.
Ein häufiger Fehler ist, bei jedem Versuch einen neuen Schlüssel zu erzeugen. Der Header sieht dann korrekt aus, schützt aber nicht: Für den Server ist jeder Versuch eine andere Operation.
Fehler bei KI und Szenarioeinstellungen
Managed AI meldet not_available (Funktion aus), not_entitled (kein Anspruch), budget_exceeded (Budget verbraucht), rate_limited, provider_unavailable und schema_validation_failed (Antwortformat ungültig). Wiederholen Sie nur Fehler, deren Antwort das erlaubt, mit demselben Idempotency-Key. Bei 4xx außer 429 oder fehlgeschlagener Schema-Prüfung korrigieren Sie die Anfrage; ein anderer Modellanbieter löst das nicht.
Meldet Copilot stale_base, basiert die vorgeschlagene Reaktionsänderung auf veralteten Einstellungen: Erstellen Sie sie erneut anhand des aktuellen Schemas. Eine Änderung der Analyse-Regeln liefert 409, wenn ein anderer Aufruf die Regeln schon geändert hat. Analytik-Neuberechnung und Replay laufen als begrenzte Aufgaben: Prüfen Sie den Status einer gestarteten Aufgabe vor einer neuen. Die Meta-Verbindungsprüfung nennt einen Fehlercode, aber weder Meta-Antwortkörper noch Zugangstoken erscheinen in Fehlermeldungen.
Weiterführende Artikel
- Authentifizierung und Tokens:
401und403. - Limits und Größen:
429und Körpergrößen. - Interaktive Referenz: mögliche Fehler je Endpoint.