호출 제한

/v1 · /mcp 호출을 1분 단위로 셉니다. REST 와 MCP 는 같은 한도를 나눠 씁니다. 넘으면 그 분이 끝날 때까지 429 입니다. 초당 환산은 1분에 고르게 보낼 때의 속도입니다 — 고정 창이라 1분 안에서는 몰아 보내도 되지만, 그만큼 그 분의 나머지 시간에는 보낼 수 없습니다.

• 소유자 토큰은 앱 하나가 쇼핑몰 하나를 부르는 양입니다. 같은 앱이 쇼핑몰 둘을 연동하면 쇼핑몰마다 따로 셉니다.
• 회원 토큰은 회원 한 명마다 따로 셉니다. 한 회원의 호출이 많아도 다른 회원은 막히지 않습니다.
• 비회원 조회는 앱 전체가 하나의 한도입니다 — 쇼핑몰 화면 서버가 손님 대신 부르는 자리이므로, 응답을 서버 · CDN 에 담아 손님 수가 호출 수가 되지 않게 하세요. → 쇼핑몰 조회의 응답 캐시
• 토큰 발급 · 갱신(/api/oauth/token)은 이 한도에 들지 않습니다. 같은 토큰을 만료까지 다시 쓰세요 — 호출마다 새로 받지 않습니다.

세는 요청의 응답에는 아래 헤더가 붙습니다 — 남은 횟수를 보고 속도를 맞추세요.

HTTP/1.1 429 Too Many Requests
Retry-After: 38
X-RateLimit-Limit: 300
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1791884700

{"code":"TooManyRequests","message":"호출이 너무 많습니다. 38초 뒤 다시 시도하세요(앱 · 쇼핑몰당 분당 300회).","request_id":"req_ce01ca473a9b49cf9306597d2e25a117"}

• Retry-After 초만큼 기다렸다 다시 보냅니다. 바로 다시 보내도 같은 분 안에서는 모두 429 입니다 — 실패한 요청을 쉬지 않고 반복하면 다음 분의 한도까지 먼저 써 버려 정상 요청도 막힙니다.
• Retry-After 를 읽지 못하는 환경이면 1 · 2 · 4 · 8 · 16초로 늘려 가며 다시 보내고(지수 백오프), 다섯 번 안에 안 되면 멈추고 알립니다.
• X-RateLimit-Remaining 이 한도의 20% 아래로 내려가면 호출 간격을 늘리세요. 429 를 맞기 전에 속도를 맞추는 편이 쉽습니다.
• MCP 는 HTTP 429 와 JSON-RPC 오류 -32029 로 답합니다(같은 Retry-After).

• 목록은 size 를 키워(최대 100) 쪽 수를 줄입니다. 바뀐 것만 필요하면 날짜 조건으로 범위를 좁힙니다.
• 여러 상품을 한 번에 바꿀 때는 상품 일괄 처리(한 번에 1,000개)를 씁니다. 상품마다 PATCH 를 보내지 않습니다.
• 대량 동기화는 병렬 대신 순차로 보내고, 쇼핑몰이 바쁜 시간대를 피해 돌립니다.
• 비회원 조회 응답은 Cache-Control: public, max-age=60 입니다. 서버 · CDN 에 담으면 손님이 늘어도 호출은 늘지 않습니다.