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

{
  "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

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: <scope>	Le jeton n'a pas le scope que l'endpoint demande. Certaines écritures exigent aussi le scope de lecture ; voir Scopes.
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.
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.
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é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

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.

É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.

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.