指南

速率限制與錯誤

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

快取#

價格經常變動，搜尋結果請最多快取幾分鐘。