Unif API Docs속도 제한
API 키별 요청 제한, 모든 응답이 담고 있는 헤더, 그리고 에이전트가 속도를 조절하는 방법.
UnifAPI의 요청 제한은 하나뿐입니다. API 키당 60초에 60회. 제한의 단위는 키이며 워크스페이스나 엔드포인트가 아닙니다. 같은 워크스페이스의 두 키가 같은 한도를 두고 경쟁하지 않고, 자체적으로 더 엄격한 제한을 가진 작업도 없습니다.
헤더
2xx, 4xx, 5xx를 가리지 않고 모든 응답이 해당 요청에 적용되는 한도를 담고 있으므로, 현재 상태를 알기 위해 탐색용 요청을 보낼 필요가 없습니다.
| 헤더 | 의미 |
|---|---|
RateLimit-Policy | IETF 구조화 필드 형식의 정책: "api-key";q=60;w=60 (q는 요청 수, w는 윈도 초) |
RateLimit | 같은 형식의 현재 상태: "api-key";r=<남은 수>;t=<리셋까지 초> |
RateLimit-Limit | 한 윈도에서 허용되는 요청 수 |
RateLimit-Remaining | 현재 윈도에 남은 요청 수 |
RateLimit-Reset | 윈도가 리셋되기까지의 초 — Unix 타임스탬프가 아니라 상대값입니다 |
X-RateLimit-Limit / -Remaining / -Reset | 위 세 헤더의 별칭. X- 표기만 읽는 클라이언트를 위한 것입니다 |
Retry-After | 대기 초. UnifAPI가 직접 발생시킨 429에 포함됩니다 |
API 키가 확인되지 않은 응답(예: 401)은 기본 정책을 한도가 가득 찬 상태로 알려줍니다. 이미 사용한 양이 아니라, 인증 후 적용될 한도를 설명하는 값입니다.
브라우저 호출자도 모두 읽을 수 있습니다. 교차 출처 응답의 Access-Control-Expose-Headers에 나열되어 있습니다.
HTTP/1.1 200 OK
RateLimit-Policy: "api-key";q=60;w=60
RateLimit: "api-key";r=57;t=60
RateLimit-Limit: 60
RateLimit-Remaining: 57
RateLimit-Reset: 60윈도 동작
윈도는 해당 키의 가장 최근 요청을 기준으로 합니다. 그 키의 호출 없이 한 윈도가 온전히 지나면 카운터가 초기화됩니다. 버스트 여유분은 없으므로, 쌓아둔 잔량이 아니라 정상 상태의 처리율을 기준으로 설계하세요.
429 처리
async function call(url: string, init: RequestInit, attempt = 0): Promise<Response> {
const res = await fetch(url, init);
if (res.status !== 429 || attempt >= 5) return res;
const wait = Number(res.headers.get("Retry-After") ?? res.headers.get("RateLimit-Reset") ?? 1);
await new Promise((r) => setTimeout(r, wait * 1000));
return call(url, init, attempt + 1);
}지켜야 할 두 가지 규칙:
- 제한에 걸리기 전에 속도를 늦추세요. 모든 응답에서
RateLimit-Remaining을 읽고 값이0에 가까워질수록 속도를 줄이세요.429를 받고 나서야 조절을 시작하면 모든 워커가 동시에 왕복 한 번을 낭비합니다. Retry-After를 지키세요. 리미터가 실제로 필요로 하는 대기 시간입니다. 추측하면 대개 상황이 나빠집니다. 헤더가 없으면RateLimit-Reset을 사용하세요.429이후에 동시성을 높이는 것은 도움이 되지 않습니다. 제한은 키 단위입니다.
한도 상향 요청
제한은 키 단위로 설정되므로, 상향은 요금제 변경이 아니라 설정 변경입니다. 워크스페이스 ID, 실행 중인 Skill 또는 작업, 대략적인 QPS를 적어 support@unifapi.com으로 문의하세요.