API partenaire (B2B)
Errors & rate limits
Partner API error codes, per-key rate limits with X-RateLimit headers, and how to retry.
On this page
Error format#
Les corps d’erreur ont la forme { statusCode, code, message }. message est un texte lisible en anglais susceptible de changer : basez toujours votre logique sur code.
// Success
{ "success": true, "data": ..., "total": 128, "page": 1, "limit": 20 }
// Error
{ "statusCode": 401, "code": "INVALID_API_KEY", "message": "The API key is invalid." }Remarque
Error codes#
| HTTP | code | Signification et solution |
|---|---|---|
| 401 | API_KEY_REQUIRED | Aucune clé envoyée — ajoutez l’en-tête X-API-Key |
| 401 | INVALID_API_KEY | Clé mal formée ou inconnue — vérifiez qu’elle n’a pas été tronquée lors de la copie et qu’il ne s’agit pas d’une clé de l’API publique |
| 401 | KEY_REVOKED | Clé révoquée — créez-en une nouvelle |
| 401 | KEY_EXPIRED | Clé expirée (y compris une ancienne clé après la période de grâce de rotation) : utilisez la nouvelle clé |
| 403 | PARTNER_SUSPENDED | Le compte n’est pas actif — contactez esimoa |
| 403 | INSUFFICIENT_SCOPE | Requête hors des périmètres de la clé |
| 403 | IP_NOT_ALLOWED | Appel depuis une IP hors de la liste autorisée — ajoutez l’IP sortante de votre serveur |
| 404 | PRODUCT_NOT_FOUND | Produit inconnu ou arrêté |
| 429 | RATE_LIMITED | Limite de requêtes dépassée — réessayez après le nombre de secondes indiqué par Retry-After |
Rate limits#
Remarque
Les requêtes à l’API B2B sont limitées par défaut à 20,000 par heure et par clé.
La fenêtre de 3,600 secondes démarre à la première requête ; la limite par minute s’applique aussi. Les quotas comptent les appels, pas les MB transférés. Les paramètres d’exploitation peuvent modifier le quota.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
Ces en-têtes indiquent la limite horaire, les appels restants et l’heure de réinitialisation (secondes Unix). Une fois la limite horaire atteinte, HTTP 429 est renvoyé avec Retry-After en secondes. Les appels rejetés par la limite par minute ne comptent pas dans le quota horaire.
La valeur par défaut est de 300 requêtes par minute et par clé (par fenêtre de 60 secondes, partagée entre tous les serveurs). esimoa peut l’augmenter par compte selon votre contrat. Chaque réponse authentifiée contient des en-têtes de quota.
X-RateLimit-Limit— requêtes autorisées par minuteX-RateLimit-Remaining— requêtes restantes dans la fenêtre actuelleX-RateLimit-Reset— moment de réinitialisation de la fenêtre (secondes Unix)Retry-After— en cas de 429, secondes à attendre avant de réessayer
HTTP/1.1 200 OK
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1790000000
HTTP/1.1 429 Too Many Requests
Retry-After: 18
{ "statusCode": 429, "code": "RATE_LIMITED", "message": "Rate limit exceeded (300 requests per minute)." }Retrying#
- En cas de 429, attendez le nombre de secondes indiqué par Retry-After, puis réessayez.
- Réessayez les erreurs 5xx quelques fois avec un délai exponentiel.
- 400, 401, 403 et 404 ne changeront pas en réessayant — corrigez la cause.
- Mettre le catalogue en cache quelques minutes vous permet de rester largement sous la limite.
async function b2bFetch(url, attempt = 0) {
const res = await fetch(url, { headers: { 'X-API-Key': process.env.ESIMOA_PARTNER_KEY } });
if (res.status === 429 && attempt < 3) {
const wait = Number(res.headers.get('Retry-After') ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
return b2bFetch(url, attempt + 1);
}
const body = await res.json();
if (!res.ok) throw Object.assign(new Error(body.message), { code: body.code, status: res.status });
return body;
}