Limites de débit et idempotence
Limites de débit
Six compteurs, en fenêtres fixes d'une minute. Un appel les traverse tous ; le premier plein répond 429 API_RATE_LIMITED avec Retry-After.
| Compteur | Plafond | Compté par | S'applique à |
|---|---|---|---|
| Adresse | 1 200 / min | adresse IP appelante | tout appel /v1, avant même la lecture de la clé |
| Lectures | 600 / min | clé | GET, HEAD, OPTIONS |
| Écritures | 60 / min | clé | POST, PATCH, DELETE |
| Alimentation | 20 / min | clé et service | POST /services/{code}/power |
| Réinstallation | 2 / min | clé et service | POST /services/{code}/reinstall |
| Compte | 1 200 / min | compte | tout appel, toutes clés confondues |
Trois détails qui changent le comportement d'une boucle de reprise :
- Un appel refusé compte. Une rafale de
400consomme le budget d'écriture comme des appels réussis. Corrigez le corps avant de réessayer. - Renouveler une clé remet ses compteurs à zéro. Les compteurs par clé sont indexés sur l'identité du secret, et un renouvellement en crée une nouvelle.
- Les compteurs sont locaux à chaque serveur. Derrière plusieurs répliques, le plafond réellement atteint peut monter jusqu'au double du plafond nominal.
Lire les en-têtes
| En-tête | Valeur |
|---|---|
X-RateLimit-Limit | le plafond du compteur le plus serré des six |
X-RateLimit-Remaining | ce qu'il reste sur ce compteur |
X-RateLimit-Reset | horodatage en secondes epoch de la fin de la fenêtre, pas un délai |
Retry-After | sur 429 seulement : secondes à attendre, minimum 1 |
Ces en-têtes décrivent le compteur le plus serré du moment, qui n'est pas toujours le même d'un appel à l'autre.
Idempotence
Quatre routes engagent de l'argent et exigent un en-tête Idempotency-Key :
POST /ordersPOST /orders/{orderNumber}/payPOST /invoices/{code}/payPOST /services/{code}/renew
| Clé d'idempotence | Détail |
|---|---|
| Format | chaîne non vide, 128 caractères au plus. Un UUID convient |
| Absent | 400 IDEMPOTENCY_KEY_REQUIRED |
| Vide ou trop long | 400 IDEMPOTENCY_KEY_INVALID |
| Portée | la clé d'API. Deux clés peuvent utiliser la même chaîne sans se gêner |
| Conservation | 24 heures |
Ce qui définit « la même requête »
L'empreinte porte sur la méthode, le chemin concret et le corps. La même clé d'idempotence sur un autre numéro de commande est donc une requête différente.
| Situation | Réponse |
|---|---|
| Rejeu à l'identique après succès | la réponse enregistrée, avec Idempotent-Replayed: true. Rien n'est refait |
| Même clé, requête différente | 409 IDEMPOTENCY_KEY_REUSED |
| Même clé pendant que le premier appel tourne | 409 IDEMPOTENCY_IN_PROGRESS avec Retry-After |
Les refus se rejouent aussi
Un refus est un résultat : il est enregistré et rejoué. Un 402 PAYMENT_DENIED rejoué reste un 402, sans nouvel appel à la banque.
Font exception les refus levés avant toute écriture et tout débit. Ceux-là libèrent la clé : corrigez la condition et réessayez avec la même.
| Libèrent la clé | Ne la libèrent pas |
|---|---|
INSUFFICIENT_BALANCE | PAYMENT_DENIED |
NO_PAYMENT_METHOD | PAYMENT_RECORDED_MISMATCH |
PAYMENT_METHOD_ID_REQUIRED | API_KEY_SPENDING_CAP_EXCEEDED |
PAYMENT_METHOD_NOT_FOUND | PAYMENT_FAILED |
PAYMENT_METHOD_NOT_ACTIVE | toute erreur 500 |
PAYMENT_METHOD_DECRYPTION_FAILED | |
PAYMENT_METHOD_VAULT_ID_MISSING | |
PAYMENT_IN_PROGRESS | |
RENEWAL_IN_PROGRESS | |
RENEWAL_TOO_FREQUENT |
API_KEY_SPENDING_CAP_EXCEEDED est dans la colonne de droite bien qu'aucun débit n'ait eu lieu : sur POST /orders, la vérification qui fait autorité tourne après l'écriture de la commande, et libérer la clé permettrait à une reprise d'en créer une seconde. Relevez le plafond, puis réessayez avec une nouvelle clé d'idempotence.
En pratique
- Générez la clé d'idempotence avant le premier envoi, et gardez-la avec la tâche, pas en mémoire.
- Réutilisez-la telle quelle pour chaque reprise de la même tâche.
- Changez-en dès que la tâche change, ne serait-ce que d'un centime.