가이드

오류 처리

실패한 모든 v1 요청은 아래에 전체 목록이 나와 있는 동일한 JSON 형태를 반환합니다. 이 페이지는 또한 모든 오류의 doc_url이 연결되는 대상입니다. 각 코드에는 고유한 앵커 섹션이 있으므로, 실제 오류 응답에서 doc_url을 따라가면 해당 코드에 대한 설명으로 바로 이동합니다.

오류 형태

{
  "error": {
    "type": "invalid_request_error",
    "code": "missing_parameter",
    "message": "필수 매개변수가 누락되었습니다.",
    "doc_url": "https://imagetotable.ai/developers/guides/errors#missing_parameter",
    "param": "file"
  }
}
  • type — 이 오류가 속하는 광범위한 범주입니다. 모든 개별 code를 확인하지 않고 오류 처리 코드에서 대략적인 분기를 수행하는 데 유용합니다.
  • code — 구체적이고 안정적인 오류 식별자입니다. 코드에서 일치시켜야 하는 값이며, 나중에 message 문구가 개선되어도 변경되지 않습니다.
  • message — 사람이 읽을 수 있는 설명입니다. 로그 및 디버깅에 유용하며, 구문 분석용이 아닙니다.
  • doc_url — 해당 code에 대한 이 페이지 섹션의 직접 링크입니다.
  • param — 유효성 검사 스타일 오류(missing_parameter, invalid_parameter, duplicate_field_name)에만 존재하며, 오류를 발생시킨 특정 요청 필드를 지정합니다. 해당되지 않는 경우 null이 아니라 완전히 생략됩니다.

오류 유형

모든 code는 정확히 하나의 type에 속합니다:

유형의미
authentication_error요청 인증 방식에 문제가 있습니다.
invalid_request_error요청 자체의 형식이 잘못되었습니다. 매개변수가 누락되었거나 유효하지 않습니다.
not_found_errorURL에서 참조한 리소스가 존재하지 않거나 계정에 속하지 않습니다.
insufficient_credits계정에 요청한 작업을 수행할 크레딧이 충분하지 않습니다.
rate_limit_error이 엔드포인트 카테고리의 요청 속도를 초과했습니다. 자세한 내용은 속도 제한을 참조하세요.
internal_error저희 쪽에서 문제가 발생했습니다. 고객님 쪽 문제가 아닙니다.

특수 사례: processing_error

processing_error는 최상위 {"error": ...} 응답에서 볼 수 있는 type이 아닙니다. 이 오류로 인해 API 호출 자체가 실패하지는 않습니다. 대신, 배치 내에서 추출할 수 없었던 개별 문서를 설명합니다. 성공한 동일 배치의 다른 문서들과 함께, 정상 200 OK 응답을 반환하는 GET /batches/{batch_name}/results 응답에서 해당 문서에 대해 "status": "failed"로 표시됩니다. 성공한 API 호출 내의 문서 수준 실패를 전체 배치를 재시도해야 하는 오류로 간주하지 마십시오. 각 문서의 개별 status를 확인하세요.

오류 코드

missing_api_key

유형: authentication_error · HTTP 상태: 401

API 키가 제공되지 않았습니다. Authorization: Bearer <key> 형식으로 전송하세요.

invalid_api_key

유형: authentication_error · HTTP 상태: 401

제공된 API 키가 유효하지 않거나, 해당 계정이 비활성화되었습니다.

plan_required

유형: authentication_error · HTTP 상태: 403

Free 요금제에서는 API를 사용할 수 없습니다. Basic 이상으로 업그레이드하여 사용하세요.

missing_parameter

유형: invalid_request_error · HTTP 상태: 400

필수 매개변수가 누락되었습니다. 오류 객체의 param 필드에서 어떤 매개변수인지 확인하세요.

invalid_parameter

유형: invalid_request_error · HTTP 상태: 400

매개변수의 값이 유효하지 않습니다. 자세한 내용은 param 및 message를 확인하세요. 이 코드는 잘못된 crop 문자열부터 범위를 벗어난 limit, 처리할 항목이 없는 배치까지 모든 상황을 포괄합니다.

duplicate_field_name

유형: invalid_request_error · HTTP 상태: 400

이 템플릿에 동일한 이름의 필드가 이미 존재합니다. 필드 이름은 템플릿 내에서 고유해야 합니다.

idempotency_key_reused

유형: invalid_request_error · HTTP 상태: 400

이 Idempotency-Key는 다른 매개변수를 가진 요청에 이미 사용되었습니다. 완전히 다른 요청에는 새 키를 사용하세요. 자세한 동작은 멱등성을 참조하세요.

document_not_found

유형: not_found_error · HTTP 상태: 404

지정된 ID의 문서를 찾을 수 없습니다.

batch_not_found

유형: not_found_error · HTTP 상태: 404

지정된 이름의 배치를 찾을 수 없습니다.

template_not_found

유형: not_found_error · HTTP 상태: 404

지정된 ID의 템플릿을 찾을 수 없습니다.

insufficient_credits

유형: insufficient_credits · HTTP 상태: 402

이 작업을 수행하기에 크레딧이 부족합니다. 재시도하기 전에 GET /account에서 현재 available_credits를 확인하세요.

rate_limit_exceeded

유형: rate_limit_error · HTTP 상태: 429

요청이 너무 많습니다. 속도를 줄이고 윈도우가 재설정된 후 재시도하세요. X-RateLimit-Reset 응답 헤더와 속도 제한 가이드를 참조하십시오.

internal_error

유형: internal_error · HTTP 상태: 500

예상치 못한 오류가 발생했습니다. 이 문제가 지속되면 저희 쪽 문제이지 사용자분 탓이 아닙니다. 문제를 안정적으로 재현할 수 있다면 문의 시 해당 정보를 포함해 주시면 도움이 됩니다.

📮 contact email: [email protected]