Limites de requêtes

Chaque requête faite avec un jeton d'installation passe par deux compteurs par minute : celui de votre installation, puis celui de la boutique. Les écritures exigent aussi un en-tête Idempotency-Key pour qu'une nouvelle tentative ne s'exécute jamais deux fois.

Quota par installation

Chaque installation de votre application dispose de son propre budget de 120 requêtes par minute. Il est vérifié en premier : une application qui boucle sur une boutique atteint sa propre limite avant de pouvoir épuiser le budget de la boutique du marchand.

Le compteur est une fenêtre fixe qui repart à zéro au début de chaque minute de l'horloge. Chaque requête compte, y compris celles qui échouent. Les requêtes refusées avec 429 comptent aussi : réessayer en boucle serrée ne rapproche pas la remise à zéro.

Quota de la boutique

Après le quota de l'installation, la requête est décomptée du budget par minute de la boutique. Ce budget est partagé par toutes les clés et toutes les applications de la boutique, y compris les propres clés API du marchand. Les jetons d'installation reçoivent le budget Enterprise de 600 requêtes par minute, quel que soit le plan de la boutique, sauf si DZBuild a fixé une autre limite pour cette boutique.

La passerelle https://api.dzbuild.app applique aussi un plafond de 600 requêtes par minute et par boutique avant que la requête n'atteigne les serveurs de DZBuild. Elle ignore une autre limite fixée par DZBuild pour une boutique : cette boutique reste plafonnée à 600 à ce niveau.

Quelques endpoints coûteux ont un budget supplémentaire par boutique, en plus de ces deux quotas :

Endpoints	Limite par boutique
Envoi d'image produit	10 par minute, 3 en même temps
Envoi au transporteur, liaison, test et synchronisation des tarifs du transporteur	6 par minute, 2 en même temps
Écritures des sections de l'accueil	30 par minute, 5 en même temps

429 Too Many Requests

Quand un quota est plein, l'API répond 429 :

{
  "error": {
    "code": "rate_limited",
    "message": "Per-minute API limit exceeded for this app install",
    "retry_after": 23
  },
  "meta": { "request_id": "8f2c1a9d4b7e6035", "api_version": "v1" }
}

La réponse porte aussi un en-tête Retry-After avec le même nombre de secondes. Le message indique quel quota est plein : Per-minute API limit exceeded for this app install pour le vôtre, Per-minute API limit exceeded for this store pour celui de la boutique. Le refus du plafond de la boutique par la passerelle elle-même se lit Per-minute API limit exceeded for this key. Attendez retry_after secondes, puis renvoyez la requête avec le même Idempotency-Key.

Trop d'opérations coûteuses en cours au même moment répondent 429 avec le code too_many_concurrent et un retry_after de 5 secondes.

402 Payment Required

Un 402 signifie que l'appel ne peut pas aboutir tant que le marchand n'a pas payé quelque chose. Réessayer ne sert à rien. Indiquez plutôt au marchand quoi faire.

Code	Signification
no_credit	Le solde WhatsApp de la boutique est vide (voir API WhatsApp). Le marchand le recharge dans le tableau de bord.
quota_exceeded	La boutique a atteint un quota mensuel de requêtes que DZBuild lui a fixé.

Idempotency-Key

Les requêtes POST, PATCH et DELETE doivent porter un en-tête Idempotency-Key. Les requêtes GET et PUT n'en ont pas besoin.

POST /v1/orders HTTP/1.1
Host: api.dzbuild.app
Authorization: Bearer dzpk_live_xxxxxxxx
Idempotency-Key: create-order-7f3a9c21
Content-Type: application/json

Les règles, telles que l'API les applique :

• La clé fait au plus 64 caractères parmi A-Z, a-z, 0-9, _, -, : et .. Une clé absente ou mal formée répond 400 avec le code bad_request.
• Une clé appartient à un jeton d'installation. Les clés de deux installations différentes n'entrent jamais en collision.
• DZBuild conserve la réponse 24 heures. Renvoyer la même clé avec la même méthode, le même chemin et le même corps renvoie le statut et le corps enregistrés sans exécuter de nouveau la requête, avec l'en-tête Idempotency-Replay: 1.
• Réutiliser la même clé avec une autre méthode, un autre chemin ou un autre corps répond 422 avec le code idempotency_key_reuse. La chaîne de requête n'entre pas dans la comparaison.
• Les réponses 4xx sont aussi enregistrées. Si une requête a échoué en 4xx et que vous corrigez le corps, envoyez-la avec une nouvelle clé.
• Les réponses 5xx et 429 ne sont pas enregistrées : une nouvelle tentative avec la même clé exécute de nouveau la requête.
• La réponse est enregistrée à la fin de la première requête. Deux requêtes envoyées au même instant avec la même clé peuvent s'exécuter toutes les deux : n'envoyez pas de tentatives en parallèle.

Générez une clé par opération, par exemple à partir de votre propre identifiant de tâche, et réutilisez-la pour chaque nouvelle tentative de cette opération.