Pour: Administrateurs
Gérer les erreurs et les codes d'état de l'API
Lisez le corps de l'erreur, ce que signifient les codes 400, 401, 403, 404, 500 et 503, et pourquoi un élément que votre clé ne peut pas voir renvoie la réponse 404.
Dans cet article5 sections
Cette page explique comment les deux API rapportent une appelée rejetée, que ce soit pour une clé de gestion ou pour une clé de hub.
Le corps de l'erreur
Chaque appel rejeté renvoie un code d’état et un corps JSON.
{
"error": {
"code": 400,
"message": "CaseReferenceIdExistsException",
"error_type": "ClientException",
"reason": {"case_id": "cc-1a2b3c4d5e6f70", "host_id": "ca-7e6d5c4b3a2f10"}
}
}
| Champ | Ce qu'il contient |
|---|---|
code | Le code de statut est de nouveau affiché. |
message | Le nom de l’erreur est CaseReferenceIdExistsException. Faites en sorte que votre code fonctionne avec ce nom ; il ne change pas en fonction du langage utilisé par le lecteur. |
error_type | Le type d’erreur : ClientException pour un refus, ApiException pour une demande inviable, SessionException pour une clé manquante, ModelException pour une clé refusée ou un refus provenant du stockage de données, TransientException pour une erreur temporaire qui mérite une répétition de la tentative, InternalError pour une panne dans CaseActive. |
reason | Des détails supplémentaires, si jamais ils existent : les identifiants des enregistrements qui ne correspondent pas entre eux, ou le problème lié au premier champ de données. Souvent, ces informations sont vides. |
errors | Pour une demande non valide, une seule entrée par champ est acceptée. |
Erreurs de terrain
Une demande qui contient des champs manquants ou invalides reçoit une réponse de type 400 SchemaFieldsException. Pour chaque champ manquant, il y a une entrée correspondante dans le champ errors. Le champ location indique le nom du champ concerné ; les points sont utilisés pour indiquer qu’il s’agit d’un champ contenant un autre champ. Le champ message indique le problème rencontré.
{
"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 correspond à json pour les paramètres du corps du message, et à query pour les paramètres de l’adresse. Erreurs courantes dans les champs :
message | Qu'est-ce qui ne va pas |
|---|---|
FieldRequiredException | Il manque quelque chose… Ou plutôt, il y a un vide là où il ne devrait pas y en avoir. |
FieldValidatorFailedException | Sa valeur n’est pas autorisée. Par exemple, il ne peut pas s’agir d’un rôle, d’un type de cas ou d’une étape que votre hub ne possède pas. |
FieldMinLengthException, FieldMaxLengthException | C’est soit trop court, soit trop long. |
FieldLimitTooLargeException | La liste contient plus de 1000 éléments limit. C’est le maximum de données qu’une page peut contenir. |
FieldEmailTypeException, FieldPhoneTypeException | Pas d’adresse e-mail, ni de numéro de téléphone avec son code pays. |
FieldNameTypeException | Un nom qui ne peut contenir de caractères… |
FieldPathSlugTypeException | Un ID ou ID de référence contenant des caractères autres que des lettres, des chiffres, des barres et des croches. |
FieldDateTypeException | Pas de date, comme par exemple 2026-03-15 |
Les informations que l’API ne reconnaît pas sont ignorées, et non rejetées. Il est donc conseillé de vérifier votre orthographe en comparant avec la version de référence.
Codes d'état
| Statut | Ce que cela signifie | Ce qu'il faut faire |
|---|---|---|
| 400 | La demande est inviable, ou la modification n’est pas autorisée. Il s’agit d’une erreur de champ, ou d’une refusée, comme indiqué dans message, par exemple CaseReferenceIdExistsException. | Corrigez-le avant de le renvoyer. |
| 401 | La clé elle-même a été refusée. Veuillez consulter la section Authentification des demandes API avec une clé. | Arrêtez-vous et vérifiez la clé. |
| 403 | La clé ne peut pas effectuer ces actions : une appelée de clé de gestion ne peut pas effectuer une opération de type (BotNotAllowedException), un hub verrouillé (ManageBillingInactiveException pour une clé de gestion, BillingReadOnlyException pour une clé d’hub une fois que le portail devient uniquement consultable), un cas fermé (CaseClosedException), ou une modification qui entre en conflit avec une autre modification effectuée au même moment (ItemUpdateFailedException et autres). | Identifiez la cause du problème. En cas de conflit, lisez à nouveau le texte concerné, puis réessayez. |
| 404 | L’article n’existe pas, il appartient à un autre hub, ou bien il est en train d’être supprimé. De plus, votre clé ne peut pas l’accéder. | Vérifiez l’identité de la personne. |
| 500 | InternalError : Une erreur dans CaseActive. Les développeurs de cette application doivent être informés de ce problème. | Réessayer plus tard. Si le problème persiste, contacter le service clientèle. |
| 503 | TransientException : Le centre de contrôle était trop occupé pour pouvoir réagir pendant un instant. | Réessayer après un court délai. Le temps de réponse augmente à chaque fois. |
Un appel qui dure plus de 30 secondes est interrompu par un message 504 provenant du réseau, sans qu’aucun corps JSON ne soit envoyé. Les imports permettent d’éviter ce problème en fonctionnant en arrière-plan.
Pourquoi un objet dont vous savez qu'il existe répond à la question 404
Une clé de hub fonctionne comme le hub de votre système. Assistante virtuelleAssistant virtuel Un membre d'équipe automatisé qui publie des messages de bienvenue, des enregistrements et des publications pour l'entreprise ; ses publications portent un badge d'assistant virtuel., Et il ne voit que ce que la fonction de l’assistant virtuel peut voir. Un élément caché à cette fonction répond au code 404 ; c’est le même code que pour un élément qui n’existe pas. Par conséquent, l’API ne le montre pas. Aujourd’hui, modifier ou supprimer une facture publiée, ou modifier une signature électronique publiée, est toujours possible, même si cette action ne peut être vue par la fonction de l’assistant virtuel. PublishAlreadyPublishedException. Les listes omettent certains éléments sans le dire explicitement. Pour savoir quel rôle cela permet, il suffit de lire les informations concernant cette fonctionnalité. role::bots Avec une clé de gestion ; voir Lisez les rôles en utilisant la clé de gestion..
Vous pouvez réessayer sans risque.
- 503, et tout ce qui concerne les
TransientException, après une courte attente. - 400
TransactionCanceledException, ce qui est causé par un moment chargé. De plus,CaseUserLimitOrTransactionExceptionne contient pas de données lorsque vous vérifiez le cas en question. - 500, un peu plus tard.
Ne tentez pas de réessayer avec les codes 400, 401, 403 ou 404, sans aucun changement : ils seront refusés à nouveau.