Documentatie

API v2-foutreferentie

Overzicht van elke gedeclareerde API v2-foutcode, HTTP-status en productietrigger.

API v2-fouten gebruiken een gestructureerd error-object:

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

Sommige validatiefouten bevatten ook een optioneel details-veld met veldspecifieke informatie:

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

Elke v2-respons bevat een x-request-id-header. Vermeld deze waarde wanneer je contact opneemt met support. Baseer je code op error.code; berichten en validatiedetails bieden alleen leesbare context voor mensen.

Foutcatalogus

De tabel bevat alle 30 codes die API v2 declareert. Een streepje betekent dat de code gereserveerd is en geen productie-v2-call site heeft, dus er is momenteel geen HTTP-status of trigger voor gedefinieerd.

CodeHTTP-statusWanneer dit gebeurtOpmerkingen
VALIDATION_INVALID_BODY400Een aanvraagtekst, padwaarde, queryparameter, limiet, cursor, gespreksbron, brontype of invoer voor bronverwerking voldoet niet aan de validatie.details wordt alleen meegegeven als de call site dat aanlevert.
VALIDATION_INVALID_JSON400Het chat-, retry-, tool-result- of feedback-endpoint ontvangt een body die geen geldige JSON is.Andere beheerendpoints interpreteren onjuist gevormde JSON als een ongeldige body.
AUTH_MISSING_API_KEY401Een endpoint dat authenticatie vereist, ontvangt geen Authorization-header, of de waarde begint niet met Bearer .Het health-endpoint vereist geen authenticatie.
AUTH_INVALID_API_KEY401De bearer-API-sleutel kan niet worden gevalideerd.Gebruik een actieve API-sleutel van de werkruimte.
AUTH_EXPIRED_API_KEY—Gereserveerd; wordt momenteel niet door een productie-v2-route gebruikt.Er is geen status of trigger voor gedefinieerd.
SUBSCRIPTION_PLAN_REQUIRED403De API-sleutel is geldig, maar de werkruimte heeft de planfunctie apiAccess niet.Voor API-toegang is minimaal het Hobby-abonnement met actieve facturering vereist.
SUBSCRIPTION_API_RESTRICTED_PLAN403Een aanroeper schakelt automatisch opnieuw trainen in zonder toegang via het abonnement, of dient een video-URL in zonder toegang tot video-transcriptie.De API-sleutel zelf blijft geldig.
AUTH_INSUFFICIENT_PERMISSIONS—Gereserveerd; wordt momenteel niet door een productie-v2-route gebruikt.Er is geen status of trigger voor gedefinieerd.
AGENT_NOT_FOUND404Een aan een agent gekoppelde aanvraag verwijst naar een agent die niet bestaat of geen eigendom is van het account van de API-sleutel.Eigendomsfouten gebruiken dezelfde respons als ontbrekende agents.
RESOURCE_NOT_FOUND404Een API v2-gesprek dat nodig is voor een detail-, bericht-, retry- of feedbackbewerking kan niet worden gevonden.Mutatie- en berichtenlijstbewerkingen hebben alleen betrekking op API v2-gesprekken.
RESOURCE_DOCUMENT_NOT_FOUND404Het verwijderen van een bron verwijst naar een document dat niet bestaat voor de agent.Ongeldige document-ID's die geen UUID zijn, geven in plaats daarvan VALIDATION_INVALID_BODY terug.
RESOURCE_MESSAGE_NOT_FOUND404Feedback verwijst naar een ongeldig bericht-ID of een bericht dat niet in het opgegeven API v2-gesprek staat.Bericht-ID's zijn positieve numerieke waarden die in responses als strings worden geserialiseerd.
RESOURCE_MESSAGE_NOT_ASSISTANT422Feedback is gericht op een bericht dat geen AI-assistant-bericht is.Gebruikersberichten en toolrecords kunnen geen feedback ontvangen.
RESOURCE_TOOL_CALL_NOT_FOUND404Het tool-result-endpoint kan de opgegeven toolCallId niet koppelen aan een openstaande clientactie.De aanroep is onbekend, verlopen of hoort bij een ander API v2-gesprek.
QUOTA_CHATBOT_LIMIT403Het aanmaken van een agent zou de chatbotlimiet van de werkruimte overschrijden.Verwijder een agent of upgrade je abonnement voordat je het opnieuw probeert.
QUOTA_STORAGE_LIMIT403Verwerking van een tekst- of Q&A-bron meldt een opslaglimiet, een nieuwe URL past niet binnen de opslag, of het aanmaken van een URL-taak meldt een quotafout.Het opnieuw trainen van een bestaande URL verbruikt geen nieuwe documentopslag.
CHAT_MODEL_NOT_ALLOWED403Een update van de AI-instellingen selecteert een model dat niet beschikbaar is op het abonnement van de werkruimte.Kies een toegestaan model of upgrade het abonnement.
CHAT_CREDITS_EXHAUSTED—Gereserveerd; wordt momenteel niet door een productie-v2-route gebruikt.Er is geen status of trigger voor gedefinieerd.
CHAT_AGENT_CREDITS_EXHAUSTED—Gereserveerd; wordt momenteel niet door een productie-v2-route gebruikt.Er is geen status of trigger voor gedefinieerd.
CHAT_CONVERSATION_MISMATCH404Een chataanvraag geeft een correct gevormde conversationId (≤128 tekens) op die niet naar een API v2-gesprek van de agent verwijst.Een conversationId langer dan 128 tekens wordt al eerder afgewezen met 400 VALIDATION_INVALID_BODY, niet met deze code. Als je conversationId weglaat, wordt een nieuw gesprek gestart.
CHAT_RETRY_MESSAGE_NOT_FOUND404Retry ontvangt een bericht-ID dat niet positief is of geen geheel getal, of het doel is geen AI-assistant-bericht in het API v2-gesprek.Toolrecords zijn geen geldig doel voor een retry.
CHAT_RETRY_NO_USER_MESSAGE400Het retry-doel heeft geen eerder gebruikersbericht om opnieuw af te spelen.Retry genereert opnieuw vanaf de gebruikersbeurt die direct voorafgaat aan het geselecteerde assistant-antwoord.
INSTAGRAM_NOT_CONNECTED404Een aanvraag voor een Instagram-kanaal noemt een agent zonder Instagram-verbinding.GET /channels/instagram antwoordt met { "connected": false } in plaats van deze code.
INSTAGRAM_RECONNECT_REQUIRED409De reactie-naar-DM-functie wordt live gezet zonder toestemming voor reacties, of gespreksstarters worden gepubliceerd voor een verbinding die niet connected is.Maak opnieuw verbinding met het account via Publiceren → Instagram in het dashboard.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409Een comment_to_dm- of story_leads-automatisering wordt live gezet terwijl een andere live instantie al op hetzelfde bericht of verhaal is gericht.Schakel de andere instantie uit of kies een ander bericht of verhaal. Concepten worden nooit afgewezen.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409Een algemene comment_to_dm- of story_leads-automatisering (postScope / storyScope "any") wordt live gezet terwijl er al een actieve algemene automatisering van dat type bestaat.Schakel eerst de bestaande algemene automatisering uit of kies een specifiek bericht of verhaal.
INSTAGRAM_SYNC_IN_PROGRESS409Een PATCH voor het permanente menu of de gespreksstarters overlapt een synchronisatie van dezelfde bron voor dezelfde agent.Probeer het opnieuw nadat de actieve publicatie of wisactie is voltooid.
INSTAGRAM_SYNC_FAILED502De synchronisatie van het permanente menu of de gespreksstarters is mislukt.details.code is een toegestane foutcode; details.http_status en details.meta_code zijn numeriek of null. De tekst van Meta's bericht wordt nooit teruggestuurd en de opgeslagen live-snapshot beschrijft nog steeds de laatst bevestigde toestand.
RATE_LIMIT_TOO_MANY_REQUESTS—Gereserveerd; wordt momenteel niet door een productie-v2-route gebruikt.Er is geen retry-timing of Retry-After-gedrag gedefinieerd.
INTERNAL_SERVER_ERROR500Het aanmaken van een URL-taak mislukt om een andere reden dan een quota, of een niet-streaming retry levert geen opgeslagen assistant-bericht op.Vermeld x-request-id wanneer je de fout meldt.

Referentie