ガイド
レート制限とエラー
公開APIのアカウントごとのレート制限、エラー形式とステータスコード、キャッシュの推奨事項です。
レート制限#
注記
公開APIと認証済みMCPはパートナー単位の時間枠（既定20,000回）を共有します。キー追加や交換で枠は増えません。
最初のリクエストから3,600秒を集計し、毎分の制限も適用します。転送MBではなく呼び出し回数です。運用設定により上限は変わります。
MCPのバッチは最大100メッセージで、各メッセージを1回として数えます。残りの上限を超えるバッチは実行前に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" }キャッシュ#
価格は頻繁に変わるため、検索結果のキャッシュは数分以内にしてください。