# 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[​](#rejouer-une-écriture-en-échec "Lien direct vers 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](https://dzbuild.com/fr/fr/api-docs/idempotency.md).

Incluez toujours `meta.request_id` lors d'un contact avec le support.