Guides
Limiti di richieste ed errori
Public API per-account rate limits, error response format, status codes and caching guidance.
On this page
Rate limits#
Nota
L’API pubblica e l’MCP autenticato condividono una quota oraria per partner (20.000 predefinite). Aggiungere o ruotare le chiavi non la aumenta.
La finestra di 3,600 secondi parte dalla prima richiesta; si applica anche il limite al minuto. Le quote contano le chiamate, non i MB trasferiti. Le impostazioni operative possono modificare la quota.
I batch MCP accettano fino a 100 messaggi e ogni messaggio conta come una chiamata. Un batch che supera la quota disponibile restituisce 429 prima dell’esecuzione.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
Questi header indicano il limite orario, le chiamate rimanenti e l’ora di reset (secondi Unix). Esaurito il limite orario, viene restituito HTTP 429 con Retry-After in secondi. Le chiamate rifiutate dal limite al minuto non vengono conteggiate nella quota oraria.
Per impostazione predefinita, ogni account partner ha un limite di 600 richieste al minuto. Oltre questo limite ricevi 429 rate_limited.
Mancia
Status codes#
| HTTP | Significato |
|---|---|
| 200 | Operazione riuscita |
| 400 | Parametri non validi |
| 401 invalid_api_key | Chiave mancante, errata o revocata |
| 404 | ID eSIM sconosciuto |
| 429 rate_limited | Limite di richieste superato |
Error format#
// 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#
I prezzi cambiano spesso: memorizza nella cache i risultati di ricerca per pochi minuti al massimo.