Documentation développeursPremiers pas
Erreurs
Un format d'erreur unique, des codes stables, des règles claires pour réessayer.
Toutes les réponses autres que 2xx ont le même format. Basez votre logique sur error.code, jamais sur message.
{
"error": {
"code": "validation_failed",
"message": "The request is invalid.",
"request_id": "req_8fK2Lq9ZtX4mN7bV1cW3yH6p",
"details": [
{
"path": "items[3].length",
"code": "out_of_range",
"message": "length must be greater than 0."
}
]
}
}| Champ | Contenu |
|---|---|
code | Stable, en snake_case |
message | En anglais, pour les journaux |
request_id | Également dans X-Request-Id. À communiquer au support |
details[] | Pour 400/422 : path, code et message de chaque problème |
Codes
| Statut | Code | Signification | Que faire | Réessayer |
|---|---|---|---|---|
| 400 | invalid_json | Le corps n'est pas un JSON valide ou un champ a un type incorrect. | Corrigez le corps de la requête. | Non |
| 401 | unauthorized | Clé API absente, mal formée ou inconnue. | Envoyez Authorization: Bearer cd_live_… ; vérifiez que la clé a été copiée en entier. | Non |
| 401 | key_revoked | La clé a été révoquée. | Créez une nouvelle clé dans la console développeur. | Non |
| 401 | key_expired | La clé a dépassé sa date d'expiration. | Créez une nouvelle clé dans la console développeur. | Non |
| 402 | insufficient_credits | Les crédits disponibles ne couvrent pas le coût minimal possible de cette tâche. | Achetez une recharge de crédits ou attendez les crédits mensuels ; rien n'a été débité. | Non |
| 403 | ip_not_allowed | L'adresse IP appelante ne figure pas dans la liste des adresses IP autorisées de la clé. | Appelez depuis une adresse IP autorisée ou modifiez la liste des adresses IP autorisées. | Non |
| 403 | subscription_inactive | L'organisation n'a aucun abonnement actif incluant l'API. | Renouvelez l'abonnement. | Non |
| 403 | account_inactive | L'organisation est suspendue ou n'a aucun propriétaire dont le compte est actif. | Contactez le support. | Non |
| 403 | scope_missing | Il manque à la clé une autorisation requise par cet endpoint. | Utilisez une clé dotée de l'autorisation requise (pack:write, jobs:read, account:read, resources:read, resources:write). | Non |
| 403 | preset_read_only | Les préréglages ne peuvent être ni modifiés ni supprimés. | Créez votre propre véhicule avec POST /v1/vehicles. | Non |
| 403 | plan_limit_reached | Le forfait de l'organisation n'autorise pas davantage de projets ou d'articles. | Supprimez les projets dont vous n'avez plus besoin ou passez à un forfait supérieur. | Non |
| 404 | not_found | Aucun endpoint /v1 n'a cette méthode et ce chemin. | Vérifiez la méthode et le chemin dans la liste des endpoints. | Non |
| 404 | job_not_found | Aucune tâche avec cet ID dans votre organisation. | Vérifiez l'ID. | Non |
| 404 | vehicle_not_found | Aucun véhicule avec cet ID parmi les préréglages ou les véhicules de votre organisation. | Vérifiez l'ID avec GET /v1/vehicles. | Non |
| 404 | template_not_found | Aucun modèle avec cet ID dans votre organisation. | Vérifiez l'ID avec GET /v1/templates. | Non |
| 404 | project_not_found | Aucun projet avec cet ID dans votre organisation. | Vérifiez l'ID avec GET /v1/projects. | Non |
| 409 | job_not_finished | La tâche est encore en file d'attente ou en cours. | Interrogez GET /v1/jobs/{id} jusqu'à ce que status vaille succeeded. | Oui |
| 409 | project_busy | Le chargement du projet est en cours de calcul (dans l'application ou par une autre tâche). | Attendez la fin de ce calcul, puis réessayez. | Oui |
| 409 | job_failed | La tâche a échoué ; elle n'a pas de résultat. | Lisez job.error ; les échecs de notre côté ne sont pas facturés (time_limit_exceeded est facturé comme une tâche annulée). Soumettez-la de nouveau si la cause était temporaire. | Non |
| 409 | job_canceled | La tâche a été annulée ; elle n'a pas de résultat. | Soumettez-la de nouveau si nécessaire. | Non |
| 409 | job_already_finished | La tâche est déjà terminée et ne peut pas être annulée. | Rien à faire. | Non |
| 400 | idempotency_key_invalid | L'en-tête Idempotency-Key dépasse 128 caractères. | Utilisez une clé plus courte (un UUID convient). | Non |
| 410 | result_expired | Le résultat a dépassé la durée de conservation et a été supprimé. | Soumettez de nouveau la tâche si vous avez encore besoin du plan. | Non |
| 413 | payload_too_large | Le corps de la requête dépasse 10 MB. | Envoyez moins d'articles ou des articles plus simples. | Non |
| 422 | validation_failed | La requête est un JSON bien formé, mais décrit une tâche invalide. details[] liste tous les problèmes. | Corrigez chaque details[].path ; les échecs de validation sont gratuits. | Non |
| 429 | rate_limited | Trop de requêtes dans la minute, l'heure ou la journée en cours (par clé ou par organisation), ou plus de 60 échecs d'authentification par minute depuis votre adresse IP. | Attendez le nombre de secondes indiqué par Retry-After, puis réessayez avec backoff. | Oui |
| 429 | too_many_jobs | L'organisation a déjà le nombre maximal de tâches en file d'attente + en cours. | Attendez la fin des tâches en cours, puis réessayez. | Oui |
| 500 | internal_error | Une erreur s'est produite de notre côté. | Réessayez avec backoff ; si le problème persiste, communiquez le request_id au support. | Oui |
| 503 | api_disabled | L'API est temporairement désactivée (maintenance) ou désactivée pour l'organisation. | Réessayez plus tard. | Oui |
Détails de validation
details[].code pour 422 validation_failed :
| Code | Signification |
|---|---|
required | Un champ obligatoire est manquant |
invalid_value | Type incorrect ou valeur non autorisée |
out_of_range | Trop petit, trop grand ou trop long |
duplicate_id | Un ID est utilisé deux fois |
unknown_vehicle | Aucun préréglage ni véhicule à vous avec ce vehicle_id |
unknown_template | Aucun modèle à vous avec ce template_id |
type_not_allowed | Type de véhicule non activé pour votre organisation |
unknown_group | Un article cite un groupe absent de la liste |
does_not_fit | L'article ne rentre dans aucun des véhicules listés |
too_many_items | Plus d'unités d'articles que la limite par tâche |
too_many_vehicles | Plus de véhicules que la limite par tâche |
unknown_field | Un champ que l'API ne connaît pas |
Erreurs de tâche
Une tâche failed ou canceled en indique la raison dans job.error.code :
| Code | Signification |
|---|---|
canceled | Annulée par DELETE /v1/jobs/{id}. Facturée : frais de base + calcul consommé. |
time_limit_exceeded | Le budget de calcul s'est épuisé avant qu'un seul véhicule soit chargé. Facturée comme une tâche annulée : frais de tâche, supplément gros chargement et calcul consommé, jamais les frais par véhicule. |
engine_failed | Le moteur de chargement a échoué. Tâche non facturée. |
queue_timeout | La tâche a attendu trop longtemps un créneau de calcul. Tâche non facturée. |
server_restarted | Le service a redémarré pendant que la tâche était en file d'attente ou en cours. Tâche non facturée. |
Nouvelles tentatives
Réessayez les 429, 500 et 503 avec un backoff exponentiel, en respectant Retry-After. Renvoyez la même Idempotency-Key (Idempotence). Pour les autres erreurs 4xx, ne renvoyez jamais la requête sans la modifier.