오류

오류는 RFC 9457 problem+json으로 반환됩니다. 모든 응답에는 correlationId가 포함되며 지원팀에 문의할 때 전달하세요.

요금제에 따른 요청 속도 제한

생성 엔드포인트의 분당 및 시간당 상한은 요금제에 따라 테넌트별로 적용되며 아래 표에 나와 있습니다. 키별이 아닌 테넌트별로 집계하므로 API 키를 추가해도 상한은 늘어나지 않습니다. 429 응답은 X-PDFgine-RateLimit-Scope 헤더에 도달한 시간 구간을 tenant-api, tenant-render-minute 또는 tenant-render-hour로 표시합니다. 일괄 작업은 요청마다 문서 하나를 보내는 대신 하나의 /document-batches 요청으로 최대 100개 문서를 보내세요.

HTTP/1.1 402 Payment Required
X-PDFgine-Quota-Remaining: 0
X-PDFgine-Metering-Basis: pdf-equivalent

{
  "title": "페이지 한도 초과",
  "status": 402,
  "detail": "요금제에서 사용할 수 있는 페이지 한도를 모두 사용했습니다.",
  "correlationId": "114249cb1dbc52a29026ab2eca5c4b72"
}

Retry-After와 제한 시간 구간

두 가지 상한이 순서대로 적용됩니다. 첫 번째는 서비스 보호를 위한 인증 정보별 한도로, 60초 구간에 키가 없으면 요청 30회, 키가 있으면 120회를 허용합니다. 두 번째는 요금제에 따른 테넌트별 한도입니다.

HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-PDFgine-RateLimit-Scope: tenant-render-minute

{
  "title": "Too many requests",
  "status": 429,
  "detail": "The request limit was exceeded. Please try again later.",
  "correlationId": "505aac87e234a7b4669e6203ac7ffcd5"
}

시간 구간은 이동식이 아닌 고정식입니다. 첫 요청 시 시작되며 구간 내 모든 요청은 같은 허용량에 합산된 후 횟수가 초기화됩니다. Retry-After는 해당 구간에 남은 초입니다. 그만큼만 기다리면 되며 더 일찍 재시도하면 거부만 한 번 더 발생합니다.

자주 발생하는 문제

• 수정 없이 4xx를 재시도하면 다시 실패합니다. 이는 서비스 혼잡이 아닌 잘못된 요청을 뜻하며 재시도할 만한 응답은 429와 5xx입니다.
• 429 응답에는 이미 Retry-After가 있습니다. 임의로 대기 시간을 정하면 시간을 낭비하거나 다시 거부됩니다.
• 402는 새벽 3시에 누군가를 호출해야 하는 장애가 아닙니다. 이번 달 한도를 소진했다는 뜻이므로 X-PDFgine-Quota-Remaining을 확인하고 미리 요금제를 높이세요.
• 다운로드의 410은 파일 분실이 아닙니다. 보관 기간이 종료된 것으로 문서는 생성되고 집계된 후 요금제에서 정한 일정에 따라 삭제되었습니다.
• 상태 코드만 기록하면 지원 요청 시 추측해야 합니다. correlationId도 함께 기록하세요. 이 값으로 요청을 찾을 수 있습니다.