Erreurs
Enveloppe d'erreur :
{ "error": { "code": "...", "message": "...", "retry_after": 12 },
"meta": { "request_id": "...", "api_version": "v1", "edge": true } }
meta.request_id et meta.api_version sont toujours présents. retry_after n'apparaît que sur les 429. meta.edge vaut true uniquement lorsque l'API a répondu directement à la requête (décisions d'authentification, de limite de débit et de cache) au lieu de la transmettre à la plateforme.
| Code | HTTP | Signification |
|---|---|---|
unauthorized | 401 | En-tête Authorization manquant / invalide |
forbidden | 403 | Authentifié mais sans le scope requis, non inscrit au pilote, ou sans plan Enterprise actif (l'API est réservée à Enterprise) |
not_found | 404 | La ressource n'existe pas ou n'appartient pas à votre boutique |
bad_request | 400 | Erreur de validation ; voir message |
method_not_allowed | 405 | Le chemin existe mais pour une autre méthode HTTP |
rate_limited | 429 | Limite par minute atteinte ; en-tête Retry-After inclus |
too_many_concurrent | 429 | Trop d'appels coûteux en cours (images, génération IA) ; réessayez dans quelques secondes |
quota_exceeded | 402 | Plafond mensuel atteint ; passez à un plan supérieur ou attendez |
server_error | 500 | Erreur serveur inattendue ; rejouez en toute sécurité les appels idempotents |
Un objet details est réservé à une future sortie de validation structurée. Aucun endpoint ne l'émet aujourd'hui : ne construisez pas de logique dessus.
Rejouer une écriture en échec
Sur https://api.dzbuild.app, une réponse 4xx renvoyée pour une écriture est mise en cache contre votre Idempotency-Key pendant 24 heures : réessayer avec la même clé rejoue exactement la même erreur, marquée Idempotency-Replay: 1, sans rien réexécuter. Corrigez la requête et renvoyez-la avec une nouvelle clé. Les erreurs renvoyées avant le traitement de la requête — 401, 403, 429 ou une Idempotency-Key mal formée — ne sont pas mises en cache, pas plus que les réponses 5xx : la même clé peut donc être réessayée sans risque. Voir Idempotence.
Incluez toujours meta.request_id lors d'un contact avec le support.