# Erreurs Cette page rassemble les erreurs décrites dans les autres pages pour que vous puissiez les traiter à un seul endroit. L'API répond à chaque erreur avec la même enveloppe JSON ; les endpoints OAuth utilisent la forme de la RFC 6749. ## L'enveloppe d'erreur de l'API[​](#lenveloppe-derreur-de-lapi "Lien direct vers L'enveloppe d'erreur de l'API") ``` { "error": { "code": "forbidden", "message": "Missing scope: orders:write" }, "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" } } ``` `error.code` est stable et destiné à votre code. `error.message` est destiné aux humains et peut changer. Citez `meta.request_id` quand vous écrivez à DZBuild au sujet d'un appel. Certaines erreurs ajoutent des champs dans `error`, par exemple `retry_after` sur un `429`. ## Codes de statut de l'API[​](#codes-de-statut-de-lapi "Lien direct vers Codes de statut de l'API") | Statut | `error.code` | Message | Cause et action | | ------ | ------------------------------- | ------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `400` | `bad_request` | variable | L'en-tête `Idempotency-Key` manque ou est mal formé sur un `POST`, `PATCH` ou `DELETE`, le corps n'est pas du JSON valide, ou un identifiant du chemin n'est pas numérique. Corrigez la requête ; envoyez une nouvelle clé. | | `401` | `unauthorized` | `Missing Authorization header` | Pas d'en-tête `Authorization`. | | `401` | `unauthorized` | `Unsupported Authorization scheme` | L'en-tête ne commence pas par `Bearer`. | | `401` | `unauthorized` | `Invalid or revoked API key` | Le jeton est faux, ou le marchand a désinstallé votre application. Traitez-le comme une désinstallation sauf si vous savez le contraire. | | `402` | `no_credit` | | Le portefeuille WhatsApp de la boutique est vide. Rien n'a été mis en file ni facturé. Réessayer ne sert à rien ; le marchand recharge depuis son tableau de bord. | | `402` | `quota_exceeded` | | La boutique a atteint un quota mensuel de requêtes fixé par DZBuild. Réessayer ne sert à rien. | | `403` | `forbidden` | `Missing scope: ` | Le jeton n'a pas le scope que l'endpoint demande. Certaines écritures exigent aussi le scope de lecture ; voir [Scopes](https://dzbuild.dev/fr/fr/scopes.md). | | `403` | `forbidden` | `Apps cannot use this endpoint` | `/v1/keys`, `/v1/webhooks` et `/v1/changes` sont fermés aux jetons d'installation. | | `403` | `app_uninstalled` | `This app is no longer installed on this store` | L'installation n'est plus active. Cessez d'utiliser le jeton et supprimez les données de la boutique. | | `403` | `app_suspended` | `This app has been suspended by DZBuild` | DZBuild a suspendu ou refusé l'application. Les appels reprennent quand la suspension est levée. | | `403` | `app_not_approved` | `This app is in test mode and only runs on its developer's stores` | L'application n'a encore jamais été approuvée et la boutique ne vous appartient pas. | | `403` | `app_plan_required` | `This app requires the ... plan` | Le plan de la boutique, ou un plan payant expiré, est inférieur au plan minimum de l'application. Dites au marchand quel plan est nécessaire. | | `403` | `addon_not_active` | | WhatsApp uniquement. Le marchand n'a pas activé l'extension WhatsApp Sender. | | `403` | `plan_required` | | Sections de la page d'accueil uniquement. L'écriture laisserait plus de sections que le plan de la boutique n'en autorise. `error` porte `plan` et `cap`. | | `404` | `not_found` | | Aucun enregistrement avec cet identifiant sur cette boutique. | | `404` | `section_not_found` | | Sections de la page d'accueil uniquement. Aucune section avec cet identifiant sur la page d'accueil de la boutique. | | `409` | `already_sent` | | WhatsApp uniquement. Ce modèle a déjà été envoyé pour cette commande. `error` porte l'`id` et le `status` du message existant. | | `409` | `write_conflict` | | Sections de la page d'accueil uniquement. Une autre écriture a changé la mise en page avant, ou la `version` envoyée sur `PUT` n'est pas l'actuelle. Quand `error` porte `sections` et `version`, repartez d'elles ; sinon, relisez la mise en page. | | `422` | `idempotency_key_reuse` | | La même `Idempotency-Key` a été envoyée avec une autre méthode, un autre chemin ou un autre corps. Une clé par opération. | | `422` | codes WhatsApp | | `unknown_template`, `invalid_language`, `invalid_number`, `suppressed`, `template_not_approved`, `empty_param`. Rien n'a été facturé. Corrigez la cause et rappelez avec une nouvelle clé. Voir [API WhatsApp](https://dzbuild.dev/fr/fr/whatsapp.md). | | `422` | codes des sections de l'accueil | | `invalid_settings` (`error.fields` liste les réglages refusés, sur `PUT` ceux de la première section refusée), `invalid_section_type`, `limit_reached`, `invalid_order`, `no_changes`. Corrigez la requête et rappelez avec une nouvelle clé. Voir [Sections de la page d'accueil](https://dzbuild.dev/fr/fr/home-layout.md). | | `429` | `rate_limited` | `Per-minute API limit exceeded for this app install` | Le budget de votre installation, 120 requêtes par minute, est épuisé. Attendez `retry_after` secondes (aussi dans l'en-tête `Retry-After`) et renvoyez avec la même `Idempotency-Key`. | | `429` | `rate_limited` | `Per-minute API limit exceeded for this store` | Le budget partagé de la boutique est épuisé. Même traitement. | | `429` | `rate_limited` | `Per-minute API limit exceeded for this key` | Le plafond de la passerelle, 600 requêtes par minute et par boutique. Même traitement. | | `429` | `too_many_concurrent` | | Trop d'opérations coûteuses en même temps (envoi d'images, appels aux transporteurs, écritures des sections de l'accueil). `retry_after` vaut 5 secondes. | | `500` | `send_failed` | | WhatsApp uniquement. Le message n'a pas pu être mis en file. Réessayez plus tard. | | `502` | `server_error` | `Key lookup failed, retry shortly` | La passerelle n'a pas pu vérifier le jeton auprès de DZBuild. Réessayez après une courte attente avec la même `Idempotency-Key`. | ## Réessayer ou non[​](#réessayer-ou-non "Lien direct vers Réessayer ou non") | Réponse | Réessayer | Avec | | --------------------------------- | ----------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- | | `429` | Oui, après `retry_after` secondes | La même `Idempotency-Key` | | `5xx` et `502` | Oui, après une courte attente | La même `Idempotency-Key` ; ces réponses ne sont jamais conservées, la requête s'exécute donc | | `400`, `401`, `403`, `404`, `422` | Non. Corrigez d'abord la cause | Une nouvelle `Idempotency-Key`, car une réponse `4xx` conservée est rejouée pendant 24 heures | | `402` | Non. Le marchand doit agir | | | `409 already_sent` | Non. Le message existe | | | `409 write_conflict` | Oui, à partir des `sections` et de la `version` de `error`, ou après avoir relu la mise en page | Une nouvelle `Idempotency-Key` | ## Erreurs OAuth[​](#erreurs-oauth "Lien direct vers Erreurs OAuth") Tant que DZBuild n'a pas fait correspondre votre `client_id` et votre `redirect_uri`, il affiche une page d'erreur au marchand et ne redirige jamais. Ensuite, il redirige vers votre `redirect_uri` avec un paramètre `error` : | `error` | Cause | | --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `unsupported_response_type` | `response_type` n'est pas `code`. | | `invalid_request` | `state` manquant ou plus long que 1024 caractères, `code_challenge` qui ne fait pas 43 caractères base64url, ou `code_challenge_method` différent de `S256`. | | `invalid_scope` | Un scope non enregistré sur l'application, non autorisé pour les applications, ou un paramètre `scope` plus long que 512 caractères. | | `access_denied` | Le marchand a cliqué sur Refuser. | L'endpoint de jeton répond en JSON avec `error` et `error_description` : | HTTP | `error` | Cause | | ----- | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `401` | `invalid_client` | `client_id` ou `client_secret` manquant ou faux. | | `400` | `unsupported_grant_type` | `grant_type` n'est pas `authorization_code`. | | `400` | `invalid_grant` | Code inconnu, expiré ou déjà utilisé, code émis pour une autre application, `redirect_uri` différente, vérificateur qui ne correspond pas, ou aucune boutique sélectionnée n'a pu être installée. | | `500` | `server_error` | Une panne de la plateforme. Renvoyez le marchand vers l'étape d'autorisation. | | `403` | aucun, corps HTML | La requête ne portait pas d'en-tête `User-Agent` : `dzbuild.com` répond à un `POST` sans cet en-tête par une page de vérification au lieu de JSON. Envoyez-en un, par exemple `my-app/1.0 (+https://example.com)`. | Un code réclamé est consommé même quand l'échange échoue ; lancez une nouvelle demande d'autorisation au lieu de réessayer avec le même code. L'ordre complet des contrôles et les pages d'erreur sont sur la page [OAuth](https://dzbuild.dev/fr/fr/oauth.md). ## Échecs de livraison des webhooks[​](#échecs-de-livraison-des-webhooks "Lien direct vers Échecs de livraison des webhooks") Une livraison réussit quand votre serveur répond `2xx` en moins de 10 secondes. Tout autre statut, une redirection, un délai dépassé ou une erreur de connexion compte comme une tentative échouée. DZBuild tente chaque livraison jusqu'à 5 fois avec des attentes croissantes, puis la marque comme abandonnée. Après 10 tentatives échouées d'affilée sur une installation, cet endpoint est désactivé ; appuyez sur Vérifier dans la console développeur pour le réactiver. Les détails et le calendrier sont sur la page [Webhooks](https://dzbuild.dev/fr/fr/webhooks.md). Votre propre vérification doit répondre `401` quand la signature ou le contrôle de l'horodatage échoue. Comme ce n'est pas une réponse `2xx`, DZBuild la compte comme une tentative échouée et réessaie ; une requête qui échoue toujours à la vérification ne vient pas de DZBuild, ou votre secret de signature n'est plus à jour.