Guides

Limites de requêtes et erreurs

Public API per-account rate limits, error response format, status codes and caching guidance.

On this page

Rate limits
Status codes
Error format
Caching

Rate limits#

Remarque

L’API publique et le MCP authentifié partagent un quota horaire par partenaire (20 000 par défaut). Ajouter des clés ou les renouveler ne l’augmente pas.

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.

Les lots MCP acceptent jusqu’à 100 messages et chaque message compte comme un appel. Un lot qui dépasse le quota disponible renvoie 429 avant exécution.

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.

Par défaut, chaque compte partenaire est limité à 600 requêtes par minute. Au-delà, vous recevez 429 rate_limited.

Pourboire

Si vous recevez une erreur 429, patientez un instant puis réessayez. Si vous répétez les mêmes recherches, mettre les résultats en cache quelques minutes est la solution la plus efficace.

Status codes#

HTTP	Signification
200	Opération réussie
400	Paramètres invalides
401 invalid_api_key	Clé manquante, incorrecte ou révoquée
404	ID d’eSIM inconnu
429 rate_limited	Limite de requêtes dépassée

Error format#

json

// 401 — missing, invalid or revoked key
{
  "error": "invalid_api_key",
  "message": "Missing or invalid API key. Create one at https://www.esimoa.com/developers/dashboard"
}

// 429 — too many requests for this key
{ "error": "rate_limited", "message": "Rate limit exceeded (600 requests per minute)." }

// 400 — invalid parameters / 404 — unknown eSIM id
{ "statusCode": 404, "message": "eSIM not found", "error": "Not Found" }

Caching#

Les prix changent souvent — ne mettez les résultats de recherche en cache que quelques minutes au maximum.