메인 콘텐츠로 건너뛰기
OrcaRouter는 API 키별이 아니라 워크스페이스 레벨에서 속도를 제한합니다. 동일 워크스페이스에 속한 모든 키가 동일한 버킷에서 인출합니다. 한도를 초과하면 Retry-After 헤더와 함께 HTTP 429 Too Many Requests 응답을 받게 됩니다.

​
왜 워크스페이스 단위인가

워크스페이스는 OrcaRouter가 단일 팀이나 개인에 속한 키, 멤버, 청구를 그룹화하는 방법입니다. 워크스페이스 내 공유 한도는 팀이 성장해도 트래픽을 예측 가능하게 유지합니다: 새 키(또는 새 멤버) 추가가 공유 예산을 곱하지 않습니다. 더 높은 천장이 필요하면 워크스페이스 플랜을 업그레이드하세요. OrcaRouter는 호출자에게 모델별 속도 제한을 노출하지 않습니다 — 프로바이더 불투명성과 일관되게 게이트웨이는 당신 애플리케이션의 관점에서 단일 논리적 프로바이더로 동작합니다. 업스트림 프로바이더에 대한 내부 스로틀링은 투명하게 일어나며 공개 계약의 일부가 아닙니다.

​
응답

속도 제한된 요청은 항상 다음을 반환합니다: 
HTTP/1.1 429 Too Many Requests
Retry-After: <seconds>
일부 속도 제한 경로는 적중된 한도를 설명하는 JSON 본문도 포함 합니다; 다른 것(가장 빠른 경로의 워크스페이스 버킷)은 상태 코드와 헤더만 반환합니다. 본문 형태에 의존하지 마세요 — 상태 코드 429와 Retry-After를 확인하세요. 본문이 있을 때는 error.type이 orcarouter_api_error로 설정된 OpenAI 호환 봉투를 따릅니다. error.message는 현지화될 수 있습니다 (현재는 중국어) — 봉투 구조는 오류 참조. Retry-After는 초 단위입니다. 속도 제한 윈도우 지속 시간입니다 (보수적 — 정확히 그만큼 기다리는 것이 안전); 다음 윈도우는 완전한 예산을 갖습니다. 기다리지 않고 즉시 재시도하면 다시 실패합니다.

​
권장 클라이언트 동작

  1. 429 시 Retry-After를 읽으세요.
  2. 해당 초만큼 대기.
  3. 동일 요청 재시도.
  4. 두 번째 429가 발생하면 대기를 2배로 늘리세요(지수 백오프), 최대 60초까지.
  5. 429가 반복되면 extra_body.models로 여러 모델에 트래픽을 분산하는 것을 고려하세요 — 모델 폴백 참조.
OpenAI Python과 TypeScript SDK는 기본적으로 Retry-After를 자동으로 처리합니다. 재시도를 비활성화하지 않았다면 커스텀 코드는 필요하지 않습니다.

​
반응적, 예측적이지 않음

OrcaRouter는 X-RateLimit-Remaining / X-RateLimit-Reset 헤더를 반환하지 않으므로 남은 예산을 미리 확인할 수 없습니다. 429를 신호로 다루세요 — 보면 물러서고 그 후 재개.