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 la passerelle api.dzbuild.app a rédigé la réponse elle-même, par exemple un refus d'authentification ou de limite de débit, ou l'échec de la vérification de la clé, au lieu de transmettre telle quelle la réponse de 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 (les clés API du marchand exigent Enterprise ; les jetons d'application installée fonctionnent avec tous les plans). Un jeton d'application le reçoit aussi, avec Apps cannot use this endpoint, sur /v1/keys, /v1/webhooks et /v1/changes |
app_uninstalled | 403 | Jeton d'application : l'application n'est plus installée sur cette boutique |
app_suspended | 403 | Jeton d'application : DZBuild a suspendu ou rejeté l'application |
app_not_approved | 403 | Jeton d'application : l'application est en mode test et cette boutique n'appartient pas à son développeur |
app_plan_required | 403 | Jeton d'application : le plan de la boutique est inférieur au plan minimum de l'application ; message nomme le plan |
not_found | 404 | La ressource n'existe pas ou n'appartient pas à votre boutique |
bad_request | 400 | Erreur de validation ; voir message |
idempotency_key_reuse | 422 | L'Idempotency-Key a déjà servi avec une autre méthode, un autre chemin ou un autre corps ; envoyez une nouvelle clé |
method_not_allowed | 405 | Le chemin existe mais pour une autre méthode HTTP |
payload_too_large | 413 | Le corps de la requête dépasse 1 Mo |
rate_limited | 429 | Limite par minute atteinte ; en-tête Retry-After inclus. Les jetons d'application ont en plus une limite propre à chaque installation, 120 requêtes par minute, vérifiée avant celle de la boutique |
too_many_concurrent | 429 | Trop d'appels coûteux en cours (images, génération IA, appels aux transporteurs, écritures des sections de l'accueil) ; 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 |
server_error | 502 | api.dzbuild.app n'a pas pu vérifier votre clé auprès de la plateforme ; réessayez dans quelques instants |
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
Une réponse 4xx renvoyée par le traitement d'une écriture est mise en cache contre votre Idempotency-Key pendant 24 heures, sur https://api.dzbuild.app comme sur l'alias dzbuild.com/api/v1 : réessayer avec la même clé et le même corps 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é ; l'ancienne répond 422 idempotency_key_reuse pour le corps modifié. Les refus prononcés avant le traitement, par exemple un 401, les 403 liés au pilote, au plan ou aux codes app_*, un 429 ou une Idempotency-Key absente ou mal formée, ne sont pas mis 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.