Dokumentation

API v2 Fehlerreferenz

Referenz aller deklarierten API-v2-Fehlercodes, HTTP-Status und Produktionsauslöser.

API-v2-Fehler verwenden ein strukturiertes error-Objekt:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body"
  }
}

Manche Validierungsfehler enthalten zusätzlich ein optionales details-Feld mit Informationen auf Feldebene:

{
  "error": {
    "code": "VALIDATION_INVALID_BODY",
    "message": "Invalid request body",
    "details": {
      "fieldErrors": {
        "message": ["Too small: expected string to have >=1 characters"]
      }
    }
  }
}

Jede v2-Antwort enthält einen x-request-id-Header. Geben Sie diesen Wert an, wenn Sie den Support kontaktieren. Prüfen Sie programmatisch gegen error.code; Nachrichten und Validierungsdetails liefern für Menschen lesbaren Kontext.

Fehlerkatalog

Die Tabelle enthält alle 30 von API v2 deklarierten Codes. Ein Gedankenstrich bedeutet, dass der Code reserviert ist und keine aktive v2-Aufrufstelle hat, sodass aktuell kein HTTP-Status oder Auslöser definiert ist.

CodeHTTP statusWhen it happensNotes
VALIDATION_INVALID_BODY400Ein Anfragetext, Pfadwert, Query-Wert, Limit, Cursor, eine Unterhaltungsquelle, ein Quelltyp oder eine Quellverarbeitungseingabe besteht die Validierung nicht.details ist nur enthalten, wenn die Aufrufstelle es bereitstellt.
VALIDATION_INVALID_JSON400Der Chat-, Retry-, Tool-Ergebnis- oder Feedback-Endpunkt erhält einen Body, der kein gültiges JSON ist.Andere Verwaltungsendpunkte werten fehlerhaftes JSON als ungültigen Body.
AUTH_MISSING_API_KEY401Ein authentifizierter Endpunkt erhält keinen Authorization-Header oder der Wert beginnt nicht mit Bearer .Der Health-Endpunkt erfordert keine Authentifizierung.
AUTH_INVALID_API_KEY401Der Bearer-API-Schlüssel kann nicht validiert werden.Verwenden Sie einen aktiven Workspace-API-Schlüssel.
AUTH_EXPIRED_API_KEY—Reserviert; wird derzeit von keiner aktiven v2-Route ausgelöst.Es ist kein Status oder Auslöser definiert.
SUBSCRIPTION_PLAN_REQUIRED403Der API-Schlüssel ist gültig, aber sein Workspace verfügt nicht über das Tarifmerkmal apiAccess.Für den API-Zugriff ist mindestens der Hobby-Tarif mit aktiver Abrechnung erforderlich.
SUBSCRIPTION_API_RESTRICTED_PLAN403Ein Aufrufer aktiviert das automatische erneute Trainieren ohne entsprechenden Tarifzugriff oder übermittelt eine Video-URL ohne Zugriff auf die Video-Transkription.Der API-Schlüssel selbst bleibt gültig.
AUTH_INSUFFICIENT_PERMISSIONS—Reserviert; wird derzeit von keiner aktiven v2-Route ausgelöst.Es ist kein Status oder Auslöser definiert.
AGENT_NOT_FOUND404Eine agentenbezogene Anfrage nennt einen Agenten, der nicht existiert oder nicht dem Konto des API-Schlüssels gehört.Fehlende Eigentümerschaft führt zur gleichen Antwort wie ein fehlender Agent.
RESOURCE_NOT_FOUND404Eine für eine Detail-, Nachrichten-, Retry- oder Feedback-Operation erforderliche API-v2-Unterhaltung wurde nicht gefunden.Mutations- und Nachrichtenlisten-Operationen betreffen ausschließlich API-v2-Unterhaltungen.
RESOURCE_DOCUMENT_NOT_FOUND404Eine Quellenlöschung nennt ein Dokument, das für den Agenten nicht existiert.Ungültige Dokument-IDs ohne UUID-Format führen stattdessen zu VALIDATION_INVALID_BODY.
RESOURCE_MESSAGE_NOT_FOUND404Feedback nennt eine ungültige Nachrichten-ID oder eine Nachricht, die sich nicht in der angegebenen API-v2-Unterhaltung befindet.Nachrichten-IDs sind positive numerische Werte, die in Antworten als Strings serialisiert werden.
RESOURCE_MESSAGE_NOT_ASSISTANT422Feedback zielt auf eine Nachricht ab, die keine KI-Assistant-Nachricht ist.Nutzernachrichten und Tool-Datensätze können kein Feedback erhalten.
RESOURCE_TOOL_CALL_NOT_FOUND404Der Tool-Ergebnis-Endpunkt kann die übergebene toolCallId keiner ausstehenden Client-Aktion zuordnen.Der Aufruf ist unbekannt, abgelaufen oder gehört zu einer anderen API-v2-Unterhaltung.
QUOTA_CHATBOT_LIMIT403Die Erstellung eines Agenten würde das Chatbot-Limit des Workspace überschreiten.Löschen Sie einen Agenten, oder führen Sie ein Upgrade durch, bevor Sie es erneut versuchen.
QUOTA_STORAGE_LIMIT403Die Verarbeitung einer Text- oder Q&A-Quelle meldet ein Speicherlimit, eine neue URL passt nicht in den verfügbaren Speicher, oder die Erstellung eines URL-Jobs meldet einen Kontingentfehler.Das erneute Trainieren einer bestehenden URL verbraucht keinen zusätzlichen Dokumentenspeicher.
CHAT_MODEL_NOT_ALLOWED403Eine Aktualisierung der KI-Einstellungen wählt ein Modell, das im Workspace-Tarif nicht verfügbar ist.Wählen Sie ein zulässiges Modell, oder upgraden Sie den Tarif.
CHAT_CREDITS_EXHAUSTED—Reserviert; wird derzeit von keiner aktiven v2-Route ausgelöst.Es ist kein Status oder Auslöser definiert.
CHAT_AGENT_CREDITS_EXHAUSTED—Reserviert; wird derzeit von keiner aktiven v2-Route ausgelöst.Es ist kein Status oder Auslöser definiert.
CHAT_CONVERSATION_MISMATCH404Eine Chat-Anfrage übergibt eine wohlgeformte conversationId (≤128 Zeichen), die sich nicht auf eine API-v2-Unterhaltung des Agenten auflösen lässt.Eine conversationId mit mehr als 128 Zeichen wird bereits vorher mit 400 VALIDATION_INVALID_BODY abgelehnt, nicht mit diesem Code. Wird conversationId weggelassen, beginnt eine neue Unterhaltung.
CHAT_RETRY_MESSAGE_NOT_FOUND404Retry erhält eine nicht positive oder nicht ganzzahlige Nachrichten-ID, oder das Ziel ist keine KI-Assistant-Nachricht in der API-v2-Unterhaltung.Tool-Datensätze sind keine Retry-Ziele.
CHAT_RETRY_NO_USER_MESSAGE400Das Retry-Ziel hat keine vorherige Nutzernachricht, die wiederholt werden kann.Retry generiert ausgehend vom Nutzerbeitrag unmittelbar vor der ausgewählten Assistant-Antwort neu.
INSTAGRAM_NOT_CONNECTED404Eine Anfrage an einen Instagram-Kanal nennt einen Agenten ohne Instagram-Verbindung.GET /channels/instagram antwortet mit { "connected": false } statt mit diesem Code.
INSTAGRAM_RECONNECT_REQUIRED409Die Kommentar-zu-DM-Funktion wird ohne Kommentarberechtigung live geschaltet, oder Unterhaltungsstarter werden für eine Verbindung veröffentlicht, die nicht connected ist.Verbinden Sie das Konto im Dashboard unter Veröffentlichen → Instagram erneut.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409Eine comment_to_dm- oder story_leads-Automatisierung wird live geschaltet, während eine andere aktive Instanz bereits auf denselben Beitrag oder dieselbe Story ausgerichtet ist.Schalten Sie die andere Instanz aus, oder wählen Sie einen anderen Beitrag oder eine andere Story aus. Entwürfe werden nie abgelehnt.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409Eine allgemeine comment_to_dm- oder story_leads-Automatisierung (postScope / storyScope "any") wird live geschaltet, obwohl bereits eine aktive allgemeine Automatisierung dieser Art vorhanden ist.Schalten Sie zuerst die vorhandene allgemeine Automatisierung aus, oder wählen Sie einen bestimmten Beitrag oder eine bestimmte Story aus.
INSTAGRAM_SYNC_IN_PROGRESS409Ein PATCH für ein dauerhaftes Menü oder Unterhaltungsstarter überschneidet sich mit einer Synchronisierung derselben Ressource desselben Agenten.Versuchen Sie es erneut, nachdem die aktive Veröffentlichung oder Löschung abgeschlossen ist.
INSTAGRAM_SYNC_FAILED502Die Synchronisierung eines dauerhaften Menüs oder von Unterhaltungsstartern ist fehlgeschlagen.details.code ist ein zugelassener Fehlercode; details.http_status und details.meta_code sind numerisch oder null. Metas Nachrichtentext wird nie zurückgegeben, und der gespeicherte Live-Schnappschuss beschreibt weiterhin den letzten bestätigten Zustand.
RATE_LIMIT_TOO_MANY_REQUESTS—Reserviert; wird derzeit von keiner aktiven v2-Route ausgelöst.Es ist kein Retry-Timing oder Retry-After-Verhalten definiert.
INTERNAL_SERVER_ERROR500Die Erstellung eines URL-Jobs schlägt aus einem anderen Grund als einem Kontingentfehler fehl, oder ein Retry ohne Streaming erzeugt keine persistierte Assistant-Nachricht.Geben Sie beim Melden des Fehlers x-request-id an.

Referenz