指南

速率限制与错误

公开 API 的每账号速率限制、错误响应格式与状态码，以及缓存建议。

本页内容

速率限制
状态码
错误格式
缓存

速率限制#

注意

公开 API 与已认证 MCP 共享每个伙伴的每小时配额（默认 20,000 次），添加或轮换密钥不会增加配额。

从首次请求起计 3,600 秒，并同时应用每分钟限制。按调用次数而非传输 MB 计算，实际配额可由运营配置调整。

MCP 批量请求最多 100 条消息，每条按一次调用计数。超出剩余配额时，在执行前返回 429。

X-RateLimit-Hour-Limit · X-RateLimit-Hour-Remaining · X-RateLimit-Hour-Reset

这些响应头表示每小时上限、剩余次数及重置时间（Unix 秒）。超限返回 HTTP 429 和 Retry-After 秒数。每分钟限制拒绝的请求不计入小时配额。

每个伙伴账号默认每分钟最多 600 次请求，超出后返回 429 rate_limited。

提示

收到 429 时请稍候再重试。若重复相同的搜索，将结果缓存几分钟最为有效。

状态码#

HTTP	含义
200	成功
400	参数错误
401 invalid_api_key	缺少、错误或已吊销的密钥
404	商品 ID 不存在
429 rate_limited	超出速率限制

错误格式#

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" }

缓存#

价格经常变动，搜索结果请最多缓存几分钟。