# API 속도 제한 — 계정별 스로틀링 및 헤더

> v1 속도 제한은 IP 주소가 아닌 계정별로 적용되며, 모든 응답에는 X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset 헤더가 포함되어 429 오류가 발생하기 전에 자체적으로 조절할 수 있습니다.

속도 제한은 인증된 계정별로 적용되며, API 키를 기준으로 합니다. IP 주소 기준이 아닙니다. 즉, 동일한 클라이언트가 여러 머신/IP에서 API에 접근하더라도 하나의 제한을 공유하며, 다른 고객이 동일한 아웃바운드 IP를 공유하더라도 서로에게 영향을 주지 않습니다.

## 엔드포인트 카테고리별 제한

| 카테고리 | 제한 | 엔드포인트 |
| --- | --- | --- |
| 업로드 / 처리 | 분당 30회 | POST /documents , POST /batches/{batch_name}/process , POST /documents/{document_id}/bbox , PUT /batches/{batch_name}/webhook |
| 상태 폴링 / 결과 | 분당 120회 | GET /documents/{document_id} , GET /batches , GET /batches/{batch_name} , GET /batches/{batch_name}/results , GET /documents/{document_id}/bbox , GET /documents/{document_id}/image , GET /account , GET /account/usage , 템플릿/필드 엔드포인트 |
| 내보내기 | 분당 10회, 시간당 60회 | GET /batches/{batch_name}/export |

이는 현재 기본값이며 시간이 지남에 따라 조정될 수 있습니다. 아래 설명된 응답 헤더는 항상 호출한 엔드포인트에 실제로 적용되는 값을 반영하므로, 이러한 숫자를 하드코딩하기보다는 헤더를 기준으로 구축하시기 바랍니다.

## 응답 헤더

속도 제한이 적용된 모든 응답에는 현재 상태를 알려주는 세 가지 헤더가 포함됩니다.

| 헤더 | 의미 |
| --- | --- |
| X-RateLimit-Limit | 현재 윈도우에서 허용된 총 요청 수입니다. |
| X-RateLimit-Remaining | 현재 윈도우에서 남은 요청 수입니다. |
| X-RateLimit-Reset | 현재 윈도우가 초기화되는 시점입니다. |

폴링 루프에서 `X-RateLimit-Remaining`을 사전에 확인하고 0이 되기 전에 대기하는 것이, 429 응답을 수동으로 처리하는 것보다 바람직합니다.

## 제한 초과 시

제한을 초과하면 HTTP 429와 함께 표준 v1 오류 형식이 반환됩니다.

```json
{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "요청이 너무 많습니다. 속도를 늦추고 윈도우가 초기화된 후에 다시 시도하세요.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#rate_limit_exceeded"
  }
}
```

배치 상태를 폴링하는 경우, 짧은 간격의 폴링 루프 대신 [웹훅](/developers/guides/webhooks)을 등록하는 것이 좋습니다. 이렇게 하면 해당 사용 사례에서 상태 폴링 제한에 걸릴 위험이 완전히 제거됩니다.

---

Source: https://imagetotable.ai/ko/developers/guides/rate-limits