GetMyBot-Wissensdatenbank

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-CodeBedeutung
200 OKAnfrage erfolgreich; Antwort enthält Daten.
201 CreatedNeue Ressource angelegt, bei manchen POST-Endpoints.
204 No ContentErfolg ohne Antwortkörper, bei manchen Löschvorgängen.
400 Bad RequestUngültiger Anfragekörper oder Parameter.
401 UnauthorizedToken fehlt, ist ungültig oder abgelaufen; oder die Route ist per PAT nicht zugänglich.
402 Payment RequiredTarif oder Quote reicht nicht, beispielsweise für Premium-Medienspeicher.
403 ForbiddenBenötigter Scope fehlt oder Tokeninhaber hat nicht das nötige Kontobereichsrecht (missing cabinet right, siehe Kontobereich des Tokens).
404 Not FoundRessource fehlt oder gehört Ihnen nicht.
409 ConflictZustandskonflikt, etwa ein doppelter eindeutiger Wert. Bei Idempotency-Key kann es auch bedeuten: dieselbe Operation läuft bereits.
413 Payload Too LargeAnfragekörper zu groß. Bei Anfragen mit Idempotency-Key gilt ein eigener niedrigerer Grenzwert von 64 KiB.
422 Unprocessable EntitySyntaktisch gültige Anfrage verletzt fachliche Regeln. Bei Idempotency-Key kann es auch heißen: gleicher Schlüssel, anderer Körper.
429 Too Many RequestsAnfragelimit überschritten, siehe Limits.
500 Internal Server ErrorInterner 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: 409 plus Retry-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

  1. Erzeugen Sie die UUID vor dem ersten Versuch und speichern Sie sie bei der Aufgabe.
  2. Senden Sie die Anfrage mit diesem Schlüssel.
  3. Bei Verbindungsabbruch, Timeout, 5xx oder 429 wiederholen Sie denselben Schlüssel.
  4. Bei 409 warten Sie Retry-After ab und wiederholen mit demselben Schlüssel.
  5. 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