가이드

요청 한도와 오류

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

캐시#

가격은 자주 바뀌니 검색 결과는 몇 분 이내로만 캐시하세요.