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.

Erreurs

Rejouer une écriture en échec