요청 한도#

정책 버전: 2026-10-01 · API v1 이 문서는 구현된 새 정책입니다. 실제 서비스에 적용된 정책은 응답 헤더와 GET /api/v1/rate-limits/policy로 확인하세요. 운영 배포 전에는 기존 응답이 유지될 수 있습니다.

ZUKU에는 성격이 다른 두 종류의 한도가 있습니다.

• API 요청 한도: 요금제·요청 종류별로 짧은 구간의 호출 속도를 제한합니다.
• CLI 게시 한도: --yolo 프로덕션 게시를 계정당 최근 6시간 동안 성공 3회로 제한합니다.

CLI 게시 한도 (--yolo)#

zuku account --quota

used(성공 수), pending(미확정 수), remaining(남은 수), reset_at(회복 시점), retry_after(대기 시간)를 보여 줍니다. 클라이언트가 표시하는 숫자는 안내용이며 판정은 서버가 합니다.

zuku agent --yolo는 모델을 호출하기 전에 남은 한도를 확인하므로, 한도가 0이면 모델 사용량을 쓰지 않고 바로 끝납니다. 게시 결과가 불확실할 때는 자동으로 다시 게시하지 않습니다. 확인 방법은 패키징과 게시와 게임 개발 에이전트를 보세요.

요금제별 기본 한도#

각 수치는 60초 동안 허용하는 요청 수입니다. 로그인 사용자는 계정별로 계산하므로 탭·기기·API 키를 늘려도 계정 한도는 늘어나지 않습니다. 비회원은 신뢰할 수 있는 프록시 경로에서 확인한 IP를 기준으로 계산합니다.

game_dedicated는 서버에서 cloud_dedicated로 정규화합니다. 한도는 호출 속도를 제한할 뿐이며, 비회원 업로드나 유료 기능을 허용하는 권한이 아닙니다. 로그인·권한·잔액·게시 조건은 각 API에서 따로 검증합니다. CLI 게시 한도는 이 표의 upload 한도와 별도로 적용됩니다.

이 기본값은 실제 클라이언트 동작을 고려해 정했습니다. AI 작업 결과 확인은 약 1.2초 간격으로 최대 약 50회/분, 미디어 변환 확인은 4초 간격으로 15회/분, DM 보조 확인은 30초 간격으로 2회/분입니다. Free 조회 600회는 여러 작업과 일반 탐색을 함께 처리할 여유를 둡니다. 게임 Cloud 브리지는 초당 최대 6회와 동시 요청 3개의 자체 제한이 있으므로 Cloud에는 별도의 10초 제한을 두지 않습니다. 이 수치는 코드상의 호출 간격으로 산출한 초기 정책이며, 운영 부하 측정 결과나 처리량 보장이 아닙니다.

요청 종류#

일반 API는 해당 종류의 한도를 사용합니다. 웹 서버가 직접 처리하는 API는 platform과 해당 API 종류를 모두 확인합니다. AI 상태 조회는 AI 시작 횟수를 쓰지 않습니다. 이미 시작한 작업은 요청 거절 때문에 취소되거나 중복 생성되지 않으며, 편집 내용은 클라이언트에서 유지합니다.

10초 구간과 인증 한도#

조회·페이지·변경·업로드·AI에는 10초 고정 구간도 적용합니다. 기본값은 분당 한도의 1/3을 올림한 값이며, 조회·페이지는 최소 20회, 변경은 최소 3회, 업로드·AI는 최소 1회입니다. Cloud에는 10초 제한을 적용하지 않습니다. 인증은 요금제와 관계없이 10초당 20회입니다. 고정 구간 경계에서는 인접 구간의 요청이 짧은 시간에 이어질 수 있으므로, 분당 수치를 일정한 초당 처리량으로 해석하면 안 됩니다.

인증은 모든 유료 요금제에서도 로그인 계정당 30회/분입니다. 비회원 인증은 IP당 120회/분이며, 기존 로그인 실패·MFA 잠금·일회용 인증 검증 조건이 더 엄격하면 그 조건이 우선합니다. 결제해도 인증 보호 수준은 낮아지지 않습니다.

민감한 인증 요청은 작은 본문을 확인한 뒤 대상별로도 제한합니다. 로그인 이메일과 핸들이 같은 계정을 가리키면 하나의 대상 한도를 쓰며, 카운터 키에는 식별자를 해시해 저장합니다. 이 조건은 결제 여부와 관계없이 적용됩니다.

인증 본문이 16 KiB를 넘으면 처리 전에 거절합니다. 일반 /auth/me·세션 목록 조회는 read, 프로필 편집은 write로 계산하므로 인증 시도 한도를 쓰지 않습니다.

IP 합산 보호#

로그인 계정에도 공유 IP에서 과도하게 합산된 요청을 막는 별도 보호 한도를 적용합니다. 일반적인 공유망 사용자를 고려해 계정 한도보다 높게 둡니다.

공유망의 비회원은 하나의 IP 한도를 함께 씁니다. 로그인하면 계정별 기본 한도를 쓰며 IP 합산 보호는 계속 적용됩니다. IP 합산 보호와 10초 제한은 요금제를 바꿔도 해제되지 않습니다.

API 키 한도#

공개 API가 인증하는 X-API-Key에는 추가로 키당 600회/분의 기본 한도가 적용됩니다. 서버 관리자가 키별 분당 한도를 따로 지정했다면 그 값을 씁니다. 여러 키는 소유 계정의 공통 한도를 함께 소비합니다. 개발자 콘솔의 키 설정은 별도 기능이며, 공개 API 인증이나 유료 요금제 판정의 근거가 아닙니다.

Cloud의 월 사용량·무료 포함량·QoS·지출 한도·AI 제공자 제한은 이 속도 제한과 별개입니다. 속도 한도를 통과해도 사용량이나 비용 조건이 맞지 않으면 작업이 거절될 수 있습니다.

응답 헤더와 재시도#

제한 대상 요청에는 실제로 측정한 다음 헤더가 붙습니다. 성공 응답은 해당 종류의 기본 60초 구간을, 429는 실제로 거절한 조건의 구간을 나타냅니다.

헬스 확인·OPTIONS·정적 자산 등 제외 요청에는 이 헤더가 없을 수 있습니다. 제한 대상의 성공 응답도 개인 한도 헤더를 담으므로 private, no-store로 제공합니다. 남은 횟수는 한 종류의 한도일 뿐이며, 다음 요청이 모든 조건을 통과한다는 보장은 아닙니다.

{
  "success": false,
  "error": {
    "code": "RATE_LIMITED",
    "message": "요청이 잠시 몰렸어요. 표시된 시간이 지난 뒤 다시 시도해 주세요.",
    "details": {
      "plan": "free",
      "scope": "read",
      "limit": 600,
      "remaining": 0,
      "window_seconds": 60,
      "retry_after_seconds": 12,
      "reset_at": 1790812860,
      "upgrade_available": true
    }
  }
}

예시 수치는 설명용입니다. 클라이언트는 실제 Retry-After를 우선하고, 값이 없으면 Reset 안내나 제한을 반환한 서비스의 오류 메시지를 따르세요. 폴링은 잠시 멈추고, 여러 작업은 큐로 분산합니다. POST·결제·업로드·AI 생성·게시 요청을 자동으로 반복하면 중복 작업이 생길 수 있으므로, 작업 상태와 기존 멱등성 계약을 먼저 확인하세요.

ZUKU 웹에서는 API 제한을 현재 화면의 안내로 보여 주고 편집 내용을 유지합니다. 페이지 탐색 자체가 제한되면 HTTP 429와 전용 /rate-limit 화면을 제공합니다. 이 화면은 확인된 대기 시간·요금제·요청 종류를 보여 주며, 기다린 뒤 돌아갈 수 있습니다. 대기 시간이 없는 제공자 오류에는 임의의 시간을 만들지 않습니다. 제한 화면·로그인·요금제·상태·공개 문서는 페이지 탐색 제한에서 제외해 회복 경로를 유지합니다.

오류 코드 전체는 오류와 응답 형식을 보세요.

정책 조회 API#

GET /api/v1/rate-limits/policy는 요금제 표, IP 합산 보호, 10초 구간 규칙, API 키 기본값을 반환합니다. 인증 없이 조회할 수 있으며 요청 카운터를 쓰지 않습니다.

POST /api/v1/rate-limits/platform은 웹 입장 확인에 쓰입니다. 서버가 Cookie/Bearer를 검증해 요금제를 결정하며, 클라이언트가 보낸 요금제·사용자 ID는 신뢰하지 않습니다. 직접 호출해도 같은 입장 한도를 소비합니다. 웹 서버가 직접 처리하는 API는 path와 method를 함께 전달해 해당 종류를 확인합니다.

운영 적용 조건#

카운터는 데이터베이스에 저장하고 원자적으로 증가시킵니다. 여러 작업자와 서버가 같은 데이터베이스를 쓰면 한도를 공유하며, 프로세스를 재시작해도 초기화되지 않습니다. 오래된 카운터는 제한된 크기의 묶음으로 정리합니다. 카운터를 확인할 수 없으면 503 RATE_LIMIT_UNAVAILABLE과 재시도 안내를 반환합니다.

이 정책은 기존 더미 헤더를 실제 한도로 전환합니다. 적용 정책·시점과 재시도 계약을 공개 문서로 먼저 안내한 뒤 웹·백엔드·문서를 함께 배포합니다.

클라이언트 IP는 직접 연결한 검증된 프록시를 통해서만 판단합니다. 외부 연결은 TCP 상대 주소를 쓰고, 신뢰한 프록시가 전달한 X-Forwarded-For는 오른쪽부터 신뢰 경로를 따라 처음 만난 외부 주소에서 멈춥니다. 브라우저가 붙인 왼쪽 주소나 사용자가 보낸 IP·요금제 헤더로 한도를 바꿀 수 없습니다.

공개 서버 데이터 조회도 요청의 확인된 IP 경로를 전달해, 모든 방문자가 웹 서버의 loopback 한도를 함께 쓰지 않게 합니다. 로그인한 상태의 공개 조회는 브라우저 Cookie에서 고른 검증 대상 세션을 별도 서버 요청 헤더 X-Zuku-Rate-Limit-Session에 담습니다. 브라우저가 보낸 같은 이름의 헤더나 요금제 필드는 재사용하지 않습니다.

백엔드는 신뢰한 실제 TCP 상대의 GET/HEAD read 요청에서만 이 세션을 검증해 계정·요금제 한도를 계산합니다. 일반 Cookie/Bearer 인증이 있으면 그것이 우선합니다. 이 식별자는 데이터 조회의 인증으로 쓰이지 않으므로 공개 조회 응답은 공개 형태 그대로이며 권한을 주지 않습니다. 변조·만료·폐기된 세션과 외부 직접 연결은 계정 한도를 얻지 못합니다. 세션 식별자가 있는 서버 요청은 no-store로 처리해 세션 값과 개인 한도 정보를 캐시에 남기지 않습니다.

HTML 문서와 피드의 동적 캐시는 모든 요청이 입장 확인을 거치도록 우회하며, 정적 자산·썸네일 캐시는 유지합니다. 공유 동적 캐시를 다시 쓰려면 캐시 적중 전에 독립적인 입장 확인을 수행하고, 개인 잔여 횟수·429·회복 화면을 공유 저장하지 않는 구조가 먼저 필요합니다.

관련 문서#

• 오류와 응답 형식
• 인증
• 게임 Cloud
• 패키징과 게시