가이드

속도 제한

속도 제한은 인증된 계정별로 적용되며, 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 오류 형식이 반환됩니다.

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

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

📮 contact email: [email protected]