Enveloppe d’erreur

Chaque réponse 2.1 porte un status numérique — 0 en cas de succès, 1 en cas d’échec — accompagné d’une courte chaîne lisible par une machine qui identifie le problème. Cette page passe en revue chaque code : ce qu’il signifie le plus souvent, et ce qu’il faut vérifier en premier.

Vous comparez les deux API ?

Les limites de débit et la sécurité des relances, pour la v3 comme pour la 2.1, sont traitées dans la page de concept sur les erreurs et les relances. Cette page-ci recense les codes de la 2.1 un par un. Erreurs, relances et limites de débit

L’enveloppe

Le succès comme l’échec passent par status ; en cas d’échec, l’opération ajoute une chaîne error :

json

{ "status": 0 }

json

{
  "status": 1,
  "error": "crid_unknown"
}

Codes

Une ligne par code de l’énumération — sa cause la plus probable, et ce qu’il faut corriger.

Codes d’erreur 2.1
Code	Cause probable	Solution
key_invalid	Le segment de clé du chemin ne correspond à aucune clé connue et active.	Vérifiez le segment de clé — une faute de frappe, une clé expirée ou une clé révoquée produisent toutes ce code.
forbidden	La clé est valide mais ne porte pas le scope exigé par cette route.	Vérifiez si la route exige client_v2 ou user_v2, et assurez-vous que la clé le porte.
auth_unavailable	La clé n’a pas pu être vérifiée car le service d’authentification était injoignable.	Réessayez — il s’agit d’un échec passager de la vérification, pas d’un rejet de la clé.
crid_unknown	Le crid du chemin n’existe pas.	Vérifiez le crid envoyé — une faute de frappe ou une référence périmée en est la cause habituelle.
data_invalid	Le corps de la requête ne correspond pas à la structure attendue par l’opération.	Comparez les champs envoyés à la référence de l’opération — retarget et modify en sont les sources habituelles.
no_message_for_this_crid	Le conteneur existe, mais aucun message n’y a encore été enregistré.	Attendez la fin de l’enregistrement, ou vérifiez si ce crid a été expédié sans message — voir le cas details ci-dessous.
message_missing	L’opération exige un message enregistré, et il n’y en a aucun.	Même cause que no_message_for_this_crid, sur une opération qui ne peut pas aboutir sans message.
no_language_found	Aucune langue n’a pu être déterminée pour la réponse.	Vérifiez qu’une langue a été définie à la création, ou qu’elle peut être déterminée autrement pour ce conteneur.
no_pdf_template	Aucun modèle PDF n’est configuré pour générer la carte.	Vérifiez qu’un modèle de carte existe pour cette plateforme avant d’appeler card.
card_renderer_unavailable	Le service de génération des cartes est injoignable.	Réessayez — il s’agit d’une défaillance passagère d’une dépendance, pas d’un problème lié à la requête.
card_renderer_failed	Le service de génération des cartes a répondu, mais n’a pas réussi à produire le PDF.	Réessayez ; si l’erreur persiste, vérifiez le contenu et le modèle de la carte pour ce crid.
webhook_not_found	Le segment webhookId du chemin ne correspond à aucun webhook configuré.	Vérifiez le webhookId — il est attribué lors de la configuration du webhook, et non choisi par l’appelant.
internal_error	Une erreur inattendue s’est produite sur le serveur.	Réessayez ; si l’erreur persiste, signalez-la en indiquant le crid et l’horodatage.

Les deux enveloppes, côte à côte

C’est la première incohérence que rencontre quiconque intègre les deux API : la v3 imbrique un code textuel sous error, tandis que la 2.1 renvoie un status numérique et place le code directement dans error.

json

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Container not found"
  }
}

json

{
  "status": 1,
  "error": "crid_unknown"
}

Le cas particulier de details

L’opération details n’échoue pas simplement quand un message manque — elle distingue un conteneur qui en attend encore un d’un conteneur qui n’en recevra jamais.

Quand un message existe, details renvoie status: 3 avec les données du message.
Quand le crid a été marqué comme expédié sans jamais recevoir de message, details renvoie status: 1 avec error: "no_message_for_this_crid" et un champ supplémentaire shipped: true.