# 요청 한도

> Nodaro API 토큰은 기본적으로 분당 30회의 실행 요청을 허용하며, 최대 120회까지 늘릴 수 있습니다. 라우트별 한도, 두 가지 429 코드, 일괄 처리 크기, 백오프 방법을 알아보세요.

Source: https://nodaro.ai/ko/docs/developers/api/rate-limits

**요청 한도**는 갑작스러운 요청 폭주로부터 Nodaro API를 보호합니다. 각 개인 API 토큰에는 워크플로 실행에 대한 분당 한도가 있고, 일부 라우트에는 자체 한도가 있으며, 한도를 넘는 요청은 `429 Too Many Requests`로 응답합니다. 작업이나 실행을 폴링해도 토큰의 한도에 포함되지 않으므로, 한도 걱정 없이 몇 초마다 폴링할 수 있습니다.

## 토큰별 한도
모든 개인 API 토큰에는 분당 요청 한도가 있습니다.

- **기본값은 분당 30회입니다.** 토큰을 만들 때 <strong>요청 한도(분당 요청 수)</strong>에서 1~120 사이로 설정합니다. 나중에 `PATCH /v1/api-tokens/:id`의 `rateLimit`으로 바꿀 수 있습니다.
- **계산되는 라우트는 두 개뿐입니다.** `POST /v1/api/run`과 `GET /v1/api/workflows`입니다.
- **읽기는 계산되지 않습니다.** `GET /v1/api/status/:execId`, `GET /v1/api/result/:execId`, `GET /v1/api/schema`는 한도를 쓰지 않습니다.
- **한도는 1분마다 초기화됩니다.**

한도를 넘는 요청은 다음과 같이 응답합니다.

```json
{ "error": { "code": "rate_limited", "message": "Too many requests. Max 30 per minute." } }
```

더 빠르게 보내려면 토큰의 한도를 120으로 높이세요. 그 이상이 필요하면 계정당 최대 10개까지 토큰을 더 만들고 요청을 나눠 보내세요. [인증](https://nodaro.ai/docs/developers/api/authentication)을 참조하세요.

## 그 밖의 한도
| 라우트 | 한도 | 초과 시 응답 |
| --- | --- | --- |
| `POST /v1/webhooks/:token`([Webhook 트리거](https://nodaro.ai/docs/nodes/automate/webhook-trigger)) | 트리거마다 분당 10회 | `429` |
| 게시된 앱의 실행 | 사용자마다 앱의 일일 실행 한도 | `429 rate_limit_exceeded` |
| `POST /v1/download-video` | 계정마다 동시에 실행되는 동영상 가져오기 4개 | `429 too_many_downloads` |
| `POST /v1/video-overlay` | 사용자마다 분당 30회 | `429 rate_limit_exceeded` |
| `POST /v1/freecut-export` | 분당 10회 | `429 rate_limit_exceeded` |
| `POST /v1/characters/:id/train` | 토큰마다 분당 3회 | `429 rate_limit_exceeded` |
| `POST /v1/oauth/register` | IP 주소마다 분당 10회 | `429 rate_limit_exceeded` |
| `POST /v1/orgs` | 사용자마다 시간당 새 조직 몇 개 | `429 rate_limit_exceeded` |
| `POST /v1/workspaces/join` | 계정마다 분당 10회, IP 주소마다 분당 30회 시도 | `429 rate_limit_exceeded` |
| `POST /v1/workflows/:id/collaborators` | 계정마다 분당 20회 추가 | `429 rate_limit_exceeded` |
| CSV 사용량 내보내기 | 사용자마다 분당 10회 | `429 rate_limit_exceeded` |
| `POST /v1/orgs/:id/invitations` | 조직마다 하루 500개 초대 | `429 bulk_invite_cap_exceeded` |
| `GET /v1/invitations/by-token/:token`, `GET /v1/shots/:id`, SSO 로그인 교환 | IP 주소마다 정해진 한도 | `429 rate_limit_exceeded` |

## 서로 다른 두 가지 429 코드
- <strong>`rate_limited`</strong>는 `/v1/api/` 라우트의 토큰별 한도에서만 나옵니다.
- <strong>`rate_limit_exceeded`</strong>는 그 밖의 모든 한도에서 나옵니다. 토큰이 필요 없는 일부 라우트의 IP 주소별 한도, 특정 라우트의 호출자별 한도, 게시된 앱의 일일 실행 한도입니다.

호출자별 한도가 있는 라우트는 `Retry-After` 헤더를 보냅니다. 크레딧을 쓰는 라우트에서 서버가 한도를 확인할 수 없으면 `503 rate_limit_unavailable`로 응답합니다.

재시도 로직은 `429` 상태를 기준으로 만드세요. 코드는 토큰별 한도와 그 밖의 한도를 구분할 때만 사용하세요.

## 한도 대처 요령
- **2~5초마다 폴링하세요.** 실행 상태는 몇 초 만에 바뀌므로, 더 자주 폴링해도 얻는 것이 없습니다.
- **한 번의 호출로 여러 작업을 폴링하세요.** `GET /v1/jobs/status`와 `POST /v1/jobs/batch-status`는 각각 최대 100개의 작업을 반환합니다. [작업](https://nodaro.ai/docs/developers/api/jobs#poll-many-jobs-at-once)을 참조하세요.
- **`429`에서는 지수적으로 백오프하세요.** 재시도할 때마다 5초, 10초, 20초를 기다리세요. `Retry-After`가 있으면 최소 그 시간만큼 기다리세요.
- **다른 `4xx` 오류는 최종 오류로 취급하세요.** 재시도하지 말고 요청을 고치세요. [오류](https://nodaro.ai/docs/developers/api/errors)를 참조하세요.

```ts

async function withBackoff<T>(call: () => Promise<T>): Promise<T> {
for (const seconds of [5, 10, 20]) {
try {
return await call()
} catch (err) {
if (!(err instanceof RateLimitedError)) throw err
await new Promise((r) => setTimeout(r, seconds * 1_000))
}
}
return call()
}

const { executionId } = await withBackoff(() => client.workflows.run(workflowId))
```

## 일괄 처리와 페이지 크기
| 엔드포인트 | 한도 |
| --- | --- |
| `GET /v1/jobs/status?ids=…` | 최대 100개 ID |
| `POST /v1/jobs/batch-status` | 최대 100개 ID |
| `GET /v1/jobs` | `limit` 최대 100 |
| `GET /v1/characters` | `limit` 최대 500, 기본값 100 |
| `GET /v1/objects`, `/v1/creatures`, `/v1/locations`, `/v1/faces` | `limit` 최대 500 |
| `GET /v1/credits/transactions` | `limit` 1~50, 기본값 20 |
| `POST /v1/credits/model-costs` | 최대 50개 모델 ID |
| `GET /v1/community/browse` | `limit` 최대 50, 기본값 20 |
| `GET /v1/orgs/:id/members` | `limit` 최대 200, 기본값 50 |
| `POST /v1/orgs/:id/invitations` | 한 번의 호출에 최대 200개 주소 |
| API 토큰 | 계정당 10개 |
| OAuth 개발자 앱 | 사용자당 직접 등록한 앱 5개 |

## 자주 묻는 질문

### Nodaro API 토큰의 요청 한도는 얼마인가요?

기본값은 분당 30회이며, 토큰마다 최대 120회까지 높일 수 있습니다. 한도는 워크플로 실행과 워크플로 목록, 즉 POST /v1/api/run과 GET /v1/api/workflows만 계산합니다.

### 폴링도 요청 한도에 포함되나요?

아니요. 실행의 상태, 결과 또는 워크플로의 스키마를 읽어도 토큰의 한도를 쓰지 않으며, 작업 상태 읽기도 마찬가지입니다. 2~5초마다 폴링하세요.

### 429 오류를 받으면 어떻게 해야 하나요?

기다렸다가 지수 백오프로 다시 시도하세요. 예를 들어 5초, 10초, 20초 뒤에 시도합니다. 응답에 Retry-After 헤더가 있으면 최소 그 시간만큼 기다리세요. 재시도 로직은 오류 코드가 아니라 429 상태를 기준으로 판단하세요.

### 요청 한도를 더 높이려면 어떻게 하나요?

토큰의 요청 한도를 분당 최대 120회까지 높이세요. 그 이상이 필요하면 계정당 최대 10개까지 토큰을 더 만들고 요청을 나눠 보내세요.

### Webhook 트리거에도 요청 한도가 있나요?

네, API 토큰과는 별도로 있습니다. 각 Webhook 트리거는 자체 URL에서 분당 10회의 요청을 받습니다.