Erreurs, relances et limites de débit
La v3 et la 2.1 signalent les échecs sous deux formes différentes, mais appliquent les mêmes limites de débit et les mêmes règles de relance. Savoir quelle API a répondu vous dit comment lire l’échec — savoir ce que vous avez appelé vous dit si le rejouer est sans risque.
Avant de lire cette page
Pour distinguer un échec d’autorisation d’un échec de validation, il faut d’abord savoir ce que les scopes d’une clé lui permettent réellement de faire. Revoir les clés d’API et les scopes
L’enveloppe d’erreur v3
Un échec v3 est un objet JSON contenant un code lisible par une machine et un message lisible par un humain, tous deux imbriqués sous error :
{
"error": {
"code": "NOT_FOUND",
"message": "Container not found"
}
}| Code | Signification |
|---|---|
| NOT_FOUND | La ressource demandée n’existe pas. |
| NO_MESSAGE | Aucun message n’est encore rattaché au conteneur. |
| MESSAGE_MISSING | L’opération nécessite un message qui n’a pas été enregistré. |
| DATA_INVALID | Le corps de la requête ne respecte pas la structure attendue. |
| EMPTY_UPDATE | Une requête PATCH ne contenait aucun champ à mettre à jour. |
| VALIDATION_ERROR | La requête a échoué à la validation pour une raison non couverte ci-dessus. |
| FORBIDDEN | La clé est valide, mais ses scopes ou ses restrictions ne couvrent pas cette requête. |
| UNAUTHORIZED | La clé est absente, inconnue ou n’a pas pu être authentifiée. |
L’enveloppe d’erreur 2.1
Une réponse 2.1 porte un status numérique au lieu d’un code de type HTTP — 0 en cas de succès, 1 en cas d’échec — accompagné d’une courte chaîne error qui identifie le problème :
{
"status": 1,
"error": "crid_unknown"
}| Code | Signification |
|---|---|
| key_invalid | Le segment de clé du chemin ne correspond à aucune clé connue. |
| forbidden | La clé est valide, mais ses scopes ne couvrent pas cette route. |
| auth_unavailable | La clé n’a pas pu être vérifiée, car le service d’authentification était injoignable. |
| crid_unknown | L’identifiant de conteneur indiqué dans le chemin n’existe pas. |
| data_invalid | Le corps de la requête n’a pas passé la validation. |
| no_message_for_this_crid | Le conteneur existe mais ne porte aucun message. |
| message_missing | L’opération nécessite un message qui n’a pas été enregistré. |
| no_language_found | Aucune langue n’a pu être déterminée pour la réponse. |
| no_pdf_template | Aucun modèle PDF n’est configuré pour générer la carte. |
| card_renderer_unavailable | Le service de rendu des cartes est injoignable. |
| card_renderer_failed | Le service de rendu des cartes a été joint, mais n’a pas pu générer la carte. |
| webhook_not_found | Le webhook référencé n’existe pas. |
| internal_error | Une erreur inattendue s’est produite sur le serveur. |
Des limites de débit identiques sur les deux API
Les deux API appliquent la même limite à deux niveaux, quelle que soit celle qui répond à la requête.
- Une limite par adresse IP s’applique en amont de l’authentification, avant toute vérification de clé.
- Une fois authentifiée, une clé est limitée à 1 000 requêtes par tranche de 15 minutes.
- Les deux limites sont identiques en v3 et en 2.1 — aucun quota distinct n’est à prévoir.
Ce qui peut être relancé sans risque
La création de conteneur est idempotente sur le crid que vous fournissez : rejouer un appel POST /containers pour un crid qui existe déjà renvoie les liens du conteneur existant, sans en créer un second ni le modifier. Cette garantie ne s’étend pas à tous les appels.