Guides
Rate limits & errors
Public API per-account rate limits, error response format, status codes and caching guidance.
On this page
Rate limits#
Note
Public API and authenticated MCP share a per-partner hourly quota (default 20,000). Adding or rotating keys does not increase it.
The 3,600-second window starts on the first request; the per-minute limit also applies. Quotas count calls, not transferred MB. Operational settings may change the quota.
MCP batches accept up to 100 messages and count each message as one call. A batch that exceeds the available quota returns 429 before execution.
X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset
These headers report the hourly limit, remaining calls and reset time (Unix seconds). Hourly exhaustion returns HTTP 429 and Retry-After in seconds. Calls rejected by the minute limit do not count toward the hourly quota.
Each partner account defaults to 600 requests per minute. Beyond that you get 429 rate_limited.
Tip
Status codes#
| HTTP | Meaning |
|---|---|
| 200 | Success |
| 400 | Invalid parameters |
| 401 invalid_api_key | Missing, wrong or revoked key |
| 404 | Unknown eSIM id |
| 429 rate_limited | Rate limit exceeded |
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#
Prices change often — cache search results for a few minutes at most.