# Limites de débit

> Un seau de jetons par clé : 60 requêtes en rafale et 5 par seconde en Sandbox. Les en-têtes de solde, le 429 et Retry-After, et ce qui consomme ou non un jeton.

Chaque clé API dispose de son propre **seau de jetons**, rempli en continu. Une requête consomme un jeton ; un seau vide fait refuser la requête en `429`.

## Les valeurs

| Environnement | Rafale (capacité du seau) | Régime soutenu |
|---|---|---|
| Sandbox | 60 requêtes | 5 requêtes par seconde, par clé |
| Production | Non publiée | Non publié |

Une clé au repos peut donc envoyer 60 requêtes d'un coup, puis continuer à 5 par seconde. Les limites de Production ne sont pas publiées : un nombre non calibré serait une promesse que nous n'avons pas mesurée. Lisez la valeur réelle de votre clé dans `Noryo-RateLimit-Limit`.

Le compteur est central : il ne dépend pas du serveur qui reçoit votre requête, et répartir votre trafic ne le contourne pas.

## Les en-têtes

| En-tête | Présent sur | Signification |
|---|---|---|
| `Noryo-RateLimit-Limit` | `200` des trois routes, et `429` | La capacité de rafale de votre clé |
| `Noryo-RateLimit-Remaining` | `200` des trois routes, et `429` | Les jetons restant dans votre seau |
| `Retry-After` | `429` | Le nombre entier de secondes avant qu'un jeton soit de nouveau disponible, au moins 1 |

Une lecture `GET` réussie et les erreurs autres que `429` ne portent pas ces en-têtes, bien qu'elles consomment un jeton. Suivez votre solde sur vos réponses `POST`, et ralentissez avant d'être refusé plutôt qu'après.

## Le 429

```http
HTTP/1.1 429 Too Many Requests
content-type: application/problem+json
retry-after: 2
noryo-ratelimit-limit: 60
noryo-ratelimit-remaining: 0
```

```json
{
  "type": "https://developer.noryo.app/errors/rate_limited",
  "title": "Rate limited",
  "status": 429,
  "code": "rate_limited",
  "detail": "Too many requests. Retry after the delay given by Retry-After.",
  "request_id": "req_…"
}
```

**Un 429 ne calcule rien et ne facture rien** : le moteur n'est pas appelé, aucun événement n'est écrit, la clé d'idempotence n'est pas réservée. Attendez `Retry-After` secondes et renvoyez la même requête, avec la même `Idempotency-Key`.

## Ce qui consomme un jeton

| Requête | Jeton consommé |
|---|---|
| Création ou rafraîchissement réussi, rejeu compris | oui |
| Lecture `GET`, réussie ou non | oui |
| Refus de validation (`400 invalid_request`, `identifier_required`), `403 insufficient_scope`, `404`, `409`, `402`, `410` | oui |
| `401` (clé absente, inconnue, révoquée), `403 account_inactive` | non |
| `400 invalid_json`, `400 invalid_idempotency_key`, `413`, `415`, hôte inconnu | non |
| `429` | non : il n'y avait plus de jeton |

En règle générale : toute requête authentifiée par une clé utilisable consomme un jeton, quelle que soit sa réponse. L'ordre exact des contrôles est décrit dans [Requêtes](https://developer.noryo.app/fr-FR/merchant/requests).

## Bonnes pratiques

1. **Respectez `Retry-After`.** C'est le délai réel avant qu'un jeton soit disponible.
2. **Lissez votre envoi.** La rafale absorbe un pic ponctuel ; le régime soutenu est la vitesse que vous pouvez tenir.
3. **Comptez par clé.** Chaque clé a son propre seau : deux services qui partagent une clé partagent aussi son débit.
4. **Gardez la même `Idempotency-Key`** entre les tentatives. Voir [Reprises](https://developer.noryo.app/fr-FR/merchant/operations/retries).

> **Note** Une panne du limiteur n'ouvre jamais le passage : le serveur rend `500 internal_error` plutôt que de laisser passer un trafic non compté. Rien n'est calculé ni facturé dans ce cas.

---

Page canonique : https://developer.noryo.app/fr-FR/merchant/rate-limits