Documentazione

Riferimento degli errori API v2

Documentazione di riferimento per ogni codice di errore dichiarato da API v2, il relativo stato HTTP e la causa scatenante in produzione.

Gli errori di API v2 usano un oggetto error strutturato:

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

Alcuni errori di validazione includono anche un campo opzionale details con informazioni a livello di campo:

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

Ogni risposta v2 include un'intestazione x-request-id. Includi questo valore quando contatti il supporto. Scrivi il tuo codice basandoti su error.code; i messaggi e i dettagli di validazione forniscono un contesto leggibile per l'utente.

Catalogo degli errori

La tabella include tutti i 30 codici dichiarati da API v2. Un trattino indica che il codice è riservato e non ha ancora un punto di chiamata in produzione su v2, quindi al momento non sono definiti né uno stato HTTP né una causa scatenante.

CodiceStato HTTPQuando si verificaNote
VALIDATION_INVALID_BODY400Un corpo della richiesta, un valore di percorso, un valore di query, il limite, il cursore, la fonte della conversazione, il tipo di sorgente o un input di elaborazione della sorgente non supera la validazione.details è incluso solo quando il punto di chiamata lo fornisce.
VALIDATION_INVALID_JSON400L'endpoint di chat, di retry, di risultato di uno strumento o di feedback riceve un corpo che non è JSON valido.Gli altri endpoint di gestione interpretano un JSON malformato come corpo non valido.
AUTH_MISSING_API_KEY401Un endpoint autenticato non riceve alcuna intestazione Authorization, oppure il valore non inizia con Bearer .L'endpoint di controllo di stato non richiede autenticazione.
AUTH_INVALID_API_KEY401La chiave API Bearer non può essere validata.Usa una chiave API attiva del workspace.
AUTH_EXPIRED_API_KEY—Riservato; al momento non viene emesso da alcuna rotta v2 in produzione.Non è definito né uno stato né una causa scatenante.
SUBSCRIPTION_PLAN_REQUIRED403La chiave API è valida, ma il suo workspace non dispone della funzionalità di piano apiAccess.L'accesso API richiede un piano Hobby o superiore con fatturazione attiva.
SUBSCRIPTION_API_RESTRICTED_PLAN403Un chiamante attiva il riaddestramento automatico senza avere accesso tramite il piano, oppure invia un URL video senza accesso alla trascrizione video.La chiave API in sé rimane valida.
AUTH_INSUFFICIENT_PERMISSIONS—Riservato; al momento non viene emesso da alcuna rotta v2 in produzione.Non è definito né uno stato né una causa scatenante.
AGENT_NOT_FOUND404Una richiesta specifica per agente indica un agente che non esiste o non appartiene all'account della chiave API.I fallimenti di proprietà usano la stessa risposta degli agenti mancanti.
RESOURCE_NOT_FOUND404Non è possibile trovare una conversazione API v2 richiesta da un'operazione di dettaglio, messaggio, retry o feedback.Le operazioni di mutazione e di elenco messaggi si applicano solo alle conversazioni API v2.
RESOURCE_DOCUMENT_NOT_FOUND404Un'eliminazione di una fonte indica un documento che non esiste per l'agente.Gli ID documento non validi e non conformi a UUID restituiscono invece VALIDATION_INVALID_BODY.
RESOURCE_MESSAGE_NOT_FOUND404Il feedback indica un ID messaggio non valido oppure un messaggio che non si trova nella conversazione API v2 specificata.Gli ID dei messaggi sono valori numerici positivi serializzati come stringhe nelle risposte.
RESOURCE_MESSAGE_NOT_ASSISTANT422Il feedback ha come obiettivo un messaggio che non è un messaggio dell'assistente AI.I messaggi utente e i record degli strumenti non possono ricevere feedback.
RESOURCE_TOOL_CALL_NOT_FOUND404L'endpoint del risultato di uno strumento non riesce ad abbinare il toolCallId fornito a un'azione client in sospeso.La chiamata è sconosciuta, scaduta o appartiene a un'altra conversazione API v2.
QUOTA_CHATBOT_LIMIT403La creazione dell'agente supererebbe il limite di chatbot del workspace.Elimina un agente o esegui l'upgrade prima di riprovare.
QUOTA_STORAGE_LIMIT403L'elaborazione di una fonte di testo o Q&A segnala un limite di archiviazione, un nuovo URL non rientra nello spazio di archiviazione disponibile, oppure la creazione del job per l'URL segnala un errore di quota.Il riaddestramento di un URL esistente non consuma nuovo spazio di archiviazione per i documenti.
CHAT_MODEL_NOT_ALLOWED403Un aggiornamento delle impostazioni AI seleziona un modello non disponibile per il piano del workspace.Scegli un modello consentito oppure esegui l'upgrade del piano.
CHAT_CREDITS_EXHAUSTED—Riservato; al momento non viene emesso da alcuna rotta v2 in produzione.Non è definito né uno stato né una causa scatenante.
CHAT_AGENT_CREDITS_EXHAUSTED—Riservato; al momento non viene emesso da alcuna rotta v2 in produzione.Non è definito né uno stato né una causa scatenante.
CHAT_CONVERSATION_MISMATCH404Una richiesta di chat fornisce un conversationId ben formato (≤128 chars) che non corrisponde a nessuna conversazione API v2 per l'agente.Un conversationId più lungo di 128 caratteri viene rifiutato prima, con 400 VALIDATION_INVALID_BODY, non con questo codice. Omettere conversationId avvia una nuova conversazione.
CHAT_RETRY_MESSAGE_NOT_FOUND404Il retry riceve un ID messaggio non positivo o non intero, oppure l'obiettivo non è un messaggio dell'assistente AI nella conversazione API v2.I record degli strumenti non sono obiettivi validi per il retry.
CHAT_RETRY_NO_USER_MESSAGE400L'obiettivo del retry non ha un messaggio utente precedente da rinviare.Il retry rigenera a partire dal turno dell'utente immediatamente precedente alla risposta dell'assistente selezionata.
INSTAGRAM_NOT_CONNECTED404La richiesta di un canale Instagram specifica un agente senza una connessione Instagram.GET /channels/instagram risponde con { "connected": false } invece di questo codice.
INSTAGRAM_RECONNECT_REQUIRED409Il passaggio dai commenti ai messaggi diretti viene attivato senza l'autorizzazione per i commenti, oppure gli spunti di conversazione vengono pubblicati su una connessione il cui stato non è connected.Riconnetti l'account in Pubblica → Instagram nella dashboard.
INSTAGRAM_AUTOMATION_TARGET_TAKEN409Un'automazione comment_to_dm o story_leads viene attivata mentre un'altra istanza attiva ha già come obiettivo lo stesso post o la stessa storia.Disattiva l'altra istanza oppure scegli un post o una storia diversi. Le bozze non vengono mai rifiutate.
INSTAGRAM_AUTOMATION_CATCH_ALL_EXISTS409Un'automazione generica comment_to_dm o story_leads (postScope / storyScope "any") viene attivata mentre esiste già un'automazione generica attiva dello stesso tipo.Prima disattiva l'automazione generica esistente oppure scegli un post o una storia specifici.
INSTAGRAM_SYNC_IN_PROGRESS409Un PATCH del menu persistente o degli spunti di conversazione si sovrappone a una sincronizzazione della stessa risorsa per lo stesso agente.Riprova al termine della pubblicazione o cancellazione attiva.
INSTAGRAM_SYNC_FAILED502La sincronizzazione del menu persistente o degli spunti di conversazione non è riuscita.details.code è un codice di errore consentito; details.http_status e details.meta_code sono numerici o null. Il testo del messaggio di Meta non viene mai restituito e l'istantanea live archiviata continua a descrivere l'ultimo stato confermato.
RATE_LIMIT_TOO_MANY_REQUESTS—Riservato; al momento non viene emesso da alcuna rotta v2 in produzione.Non sono definiti né i tempi di retry né il comportamento dell'header Retry-After.
INTERNAL_SERVER_ERROR500La creazione del job per l'URL fallisce per un motivo non legato alla quota, oppure un retry non in streaming non produce alcun messaggio dell'assistente persistito.Includi x-request-id quando segnali il problema.

Riferimenti correlati