Centro assistenzaIntegrazioni

Per: Amministratori

Gestire gli errori e i codici di stato delle API

Leggi il corpo dell'errore, cosa significano i codici 400, 401, 403, 404, 500 e 503 e perché un elemento che la tua chiave non riesce a vedere risponde al codice 404.

In questo articolo5 sezioni

Questa pagina spiega come entrambe le API comunichino l’evento di rifiuto di una chiamata, sia per la chiave di gestione che per la chiave di hub.

Il corpo dell'errore

Ogni chiamata rifiutata risponde con un codice di stato e un corpo JSON.

{
  "error": {
    "code": 400,
    "message": "CaseReferenceIdExistsException",
    "error_type": "ClientException",
    "reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
  }
}
CampoCosa contiene
codeAncora il codice di stato.
messageIl nome dell’errore è, ad esempio, CaseReferenceIdExistsException. Il tuo codice deve funzionare in base a questo valore; esso non cambia, indipendentemente dalla lingua utilizzata dal lettore.
error_typeI tipi di errori sono i seguenti: ClientException per un rifiuto dell’invio della richiesta; ApiException per una richiesta non valida; SessionException per la mancanza di una chiave necessaria per l’esecuzione della richiesta; ModelException per la mancata accettazione della chiave richiesta, oppure per un rifiuto da parte del database; TransientException per problemi temporali che richiedono una riprova della richiesta; InternalError per errori legati al funzionamento di CaseActive.
reasonPer ulteriori dettagli, quando ce ne sono: le identificazioni dei file che causano il problema, oppure i problemi legati al primo campo del file. Spesso questi dati sono vuoti.
errorsPer una richiesta non valida, è necessario inserire un solo valore per ogni campo.

Errori sul campo

Una richiesta in cui un campo è mancante o non valido genera l’errore 400 SchemaFieldsException. Per ogni campo mancante, viene indicato un valore errors. Il campo location rappresenta il nome del campo stesso; i punti utilizzati per indicare che c’è un campo all’interno di un altro campo sono importanti. Infine, il campo message indica il problema riscontrato nella richiesta.

{
  "error": {
    "code": 400,
    "message": "SchemaFieldsException",
    "error_type": "ApiException",
    "reason": "FieldRequiredException",
    "errors": [
      {"domain": "json", "location": "ref_id", "locationId": "ref_id", "locationType": "schema", "message": "FieldRequiredException", "reason": "FieldRequiredException"}
    ]
  }
}

domain corrisponde a json per i parametri del corpo del messaggio, mentre query corrisponde ai parametri dell’indirizzo. Errori comuni nei campi:

messageCosa c'è che non va?
FieldRequiredExceptionÈ mancante… o vuoto, nel punto in cui non dovrebbe esserci nulla.
FieldValidatorFailedExceptionIl suo valore non è valido, ad esempio, un ruolo, un tipo di caso o uno stato che il proprio hub non possiede.
FieldMinLengthException, FieldMaxLengthExceptionÈ troppo corto… oppure troppo lungo.
FieldLimitTooLargeExceptionIl valore di limit nella lista supera i 1000 elementi; quindi, è possibile che una pagina possa contenere fino a 1000 elementi.
FieldEmailTypeException, FieldPhoneTypeExceptionNé un indirizzo e-mail, né un numero di telefono, compreso il codice del paese in cui si trova il numero.
FieldNameTypeExceptionUn nome che non può contenere tutti i caratteri necessari per essere un nome.
FieldPathSlugTypeExceptionUn ID o un ID di riferimento che contiene caratteri diversi da lettere, numeri, trattini e barre.
FieldDateTypeExceptionNon si tratta di una data, come ad esempio 2026-03-15

I campi che l’API non conosce vengono ignorati, non rifiutati. Quindi, è necessario verificare la correttezza della scrittura dei dati rispetto a quanto indicato nella documentazione di riferimento.

Codici di stato

StatoCosa significaCosa fare
400La richiesta è inviabile, oppure il cambiamento non è permesso. Si tratta probabilmente di un errore nel campo da modificare, oppure di una negazione della richiesta, come indicato in message. Ad esempio: CaseReferenceIdExistsExceptionCorreggilo prima di inviarlo di nuovo.
401La chiave stessa è stata rifiutata. Per ulteriori informazioni, vedere Autenticare le richieste API con una chiave.Fermatevi e controllate la chiave.
403La chiave potrebbe non funzionare in questo modo: una chiamata alla chiave di gestione non può effettuare alcun comando (BotNotAllowedException); un hub bloccato (ManageBillingInactiveException per la chiave di gestione, BillingReadOnlyException per la chiave dell’hub, una volta che il portale diventa di tipo “leggero”); un caso chiuso (CaseClosedException); oppure una modifica che entra in conflitto con un’altra modifica effettuata nello stesso momento (ItemUpdateFailedException e altri casi simili).Determinare la causa del problema. In caso di conflitti, leggere nuovamente l’elemento in questione, poi provare di nuovo.
404L’articolo non esiste. Potrebbe appartenere a un altro hub, oppure è in fase di eliminazione. Inoltre, la tua chiave potrebbe non riuscire ad accedere all’articolo.Verificare l’identità del destinatario.
500InternalError: Un errore nel codice di CaseActive. I sviluppatori di questo software devono risolvere il problema.Proverò di nuovo in un altro momento. Se il problema continua, contatterò il servizio di assistenza.
503TransientException: Il hub era troppo occupato per un momento.Prova di nuovo dopo un breve periodo di attesa; ogni volta l’attesa dovrà durare più a lungo.

Una chiamata che dura più di 30 secondi viene interrotta a causa di un messaggio 504 da parte della rete, senza alcun corpo JSON da inviare. I programmi che vengono eseguiti in background evitano questo problema.

Perché sai che un oggetto esiste risponde a 404

La chiave “hub” funge da punto di riferimento per il sistema. Assistente virtualAssistente virtuale Un membro automatizzato del team che pubblica messaggi di benvenuto, check-in e post di aggiornamento per l'azienda; i suoi post sono contrassegnati da un badge di Assistente Virtuale., E vede soltanto ciò che il ruolo dell’Assistente Virtuale può vedere. Un elemento nascosto da quel ruolo genera un errore 404; lo stesso vale per gli elementi che non esistono affatto. Pertanto, l’API non riesce a rivelare tali elementi. Oggi, modificare o eliminare una fattura pubblicata, oppure modificare un documento digitale pubblicato, elementi che il ruolo dell’Assistente Virtuale non può vedere, continuano a generare l’errore 403. PublishAlreadyPublishedException. Le liste includono alcuni elementi senza indicarlo esplicitamente. Per capire quale ruolo svolgono questi elementi, bisogna leggere attentamente il testo in questione. role::bots Con una chiave di amministrazione; vedi Leggi i ruoli con la chiave “manage”..

Riprovare in sicurezza

  • 503, e qualsiasi valore di TransientException, dopo una breve attesa.
  • 400 TransactionCanceledException… Un momento particolarmente impegnativo, che causa questo problema. Inoltre, una volta verificato il caso, si scopre che CaseUserLimitOrTransactionException non è pieno.
  • 500… Un po’ più tardi.

Non provare di nuovo con altri errori del tipo 400, 401, 403 o 404… Questi errori verranno rifiutati ancora una volta.

Articoli correlati

Autentica le richieste API con una chiaveInvia la tua chiave come token bearer all'API del pannello di amministrazione per una chiave di gestione o all'API del portale per una chiave hub, e limita l'invio ai tuoi indirizzi IP.IntegrazioniComprendere cosa può fare l'APIScopri quali funzioni possono svolgere un tasto di gestione e un tasto hub, perché ogni tasto funge da Assistente Virtuale e dove trovare l'elenco tecnico completo.Integrazioni