속도 제한

RealityConnect API는 경로 계열별 토큰 버킷을 사용하여 조직별로 요청 속도를 제한합니다. 이 페이지는 버킷, 속도 제한된 모든 응답이 포함하는 헤더, 429 Too Many Requests에 대한 대응 방법을 다룹니다.

---

버킷

각 버킷에는 용량(최대 토큰 수, 즉 버스트 크기)과 충전 속도(초당 추가되는 토큰 수, 즉 지속 처리량)가 있습니다. 요청은 토큰 하나를 소비합니다; 버킷이 비어 있으면 요청은 429로 거부됩니다.

버킷	용량	충전 속도	적용 대상
assets	1000	10/s	RealityAsset, 애셋 유형, 애셋 카테고리, 비즈니스 객체 생성/읽기/목록/삭제
twin	1000	10/s	Twin 공간, POI, 존, 초안
platform	1000	10/s	사이트, 데이터 노드, 데이터 번들, 플러그인
plan	1000	10/s	Reality plan 공간, 모델 애셋
library	1000	10/s	애셋 라이브러리 모델과 태그
embed	100	2/s	임베드 세션 발급
users	1000	10/s	사용자, 그룹, 역할, 초대
sitefiles	1000	10/s	사이트 파일

속도 제한은 조직 단위로 적용됩니다: 동일한 조직을 대신하여 작동하는 모든 OAuth 애플리케이션과 사용자는 계열별로 버킷 하나를 공유합니다.

응답 헤더

성공 여부와 관계없이 속도 제한된 모든 응답에는 다음 헤더가 포함됩니다:

헤더	의미
X-RateLimit-Limit	버킷의 용량
X-RateLimit-Remaining	버킷에 남은 토큰 수
X-RateLimit-Reset	버킷이 다시 가득 찰 때까지 남은 초
X-RateLimit-Policy	{capacity};w={window} 형식이며, window(초)는 capacity / refillRate입니다

429 Too Many Requests인 경우에만, 응답에 Retry-After(토큰이 최소 하나 사용 가능해질 때까지 남은 초)와 다음 본문도 포함됩니다:

{
  "statusCode": 429,
  "message": "Too Many Requests",
  "error": "rate_limited"
}

429 처리하기

고정된 지연이나 즉시 재시도 대신 Retry-After를 사용해 백오프하세요: 비어 있는 버킷에 즉시 재시도하면 또 다른 429만 발생합니다. 지속적인 대용량 워크로드의 경우, 용량까지 버스트한 후 리셋을 기다리기보다 버킷의 충전 속도 이하로 요청 속도를 조절하세요.

다음은?

• 각 버킷에 속한 정확한 작업 목록은 API 참조를 참조하세요.