Rate Limits & Error Handling

Rate limits

The eSIM Go API applies rate limits per IP address using a fixed window algorithm. The default limit is 10 requests per second.

Rate limit headers

Every API response includes the following headers so you can monitor your usage:

Header	Description
X-Ratelimit-Limit	Total tokens available in the current window
X-Ratelimit-Remaining	Tokens remaining after this request
X-Ratelimit-Reset	ISO-8601 timestamp when the window resets
X-Ratelimit-Cost	Token cost of this request

If an endpoint costs 5 tokens and your limit is 10 per second, you can call that endpoint at most twice per second before being rate limited.

Handling 429 responses

When you exceed the rate limit, the API returns 429 Too Many Requests:

{
  "message": "Rate limit exceeded"
}

The response also includes a Retry-After header indicating how many seconds to wait before retrying:

Retry-After: 1

A simple retry pattern:

async function apiRequest(url, options, retries = 3) {
  const response = await fetch(url, options);

  if (response.status === 429 && retries > 0) {
    const retryAfter = parseInt(response.headers.get('Retry-After') || '1', 10);
    await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
    return apiRequest(url, options, retries - 1);
  }

  return response;
}

---

Error handling

All error responses use the same JSON structure:

{
  "message": "Description of the error"
}

HTTP status codes

Code	Meaning	Common causes
400	Bad Request	Malformed request body, missing required fields
403	Forbidden	Invalid or missing API key, IP not on whitelist
404	Not Found	Resource does not exist or is not accessible to your organisation
429	Too Many Requests	Rate limit exceeded
500	Server Error	Unexpected error on the eSIM Go side

400 Bad Request

Returned when the request body is malformed or a required field is missing. The message field describes the specific validation failure.

403 Forbidden

Returned for authentication failures. Check that:

• Your X-API-Key header is present and correct
• If you have IP whitelisting enabled, the request is coming from an allowed IP address

500 Server Error

Unexpected server-side errors. These are logged and monitored by eSIM Go. If you see persistent 500s, contact technical support.