오류 코드

요청이 실패하면 API는 기계 판독 가능한 code와 사람이 읽을 수 있는 message가 포함된 JSON 오류 응답을 반환합니다:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable description of the error"
  }
}

code 필드는 안정적이며 애플리케이션 로직에서 매칭하기에 안전합니다. message 필드는 시간이 지남에 따라 변경될 수 있으며 로깅 및 디버깅을 위한 것입니다.

오류 코드 레퍼런스

코드	HTTP 상태	설명	재시도 가능	해결 방법
UNAUTHORIZED	401	인증 토큰이 누락, 유효하지 않거나 만료됨	아니오	API 키가 유효하고 만료되지 않았는지 확인하세요
KEY_EXPIRED	401	API 키가 만료 날짜를 지남	아니오	대시보드 또는 API를 통해 새 API 키를 생성하세요
FORBIDDEN	403	인증되었지만 이 리소스에 대한 권한이 없음	아니오	자신의 리소스만 접근할 수 있습니다
NOT_FOUND	404	요청한 리소스가 존재하지 않음	아니오	리소스 ID가 올바른지 확인하세요
VALIDATION_ERROR	400	요청 본문이 스키마 유효성 검사에 실패	아니오	필수 필드와 데이터 타입이 스키마와 일치하는지 확인하세요
INVALID_MIME_TYPE	400	업로드된 파일의 MIME 타입이 지원되지 않음	아니오	지원되는 파일 형식(PDF 또는 DOCX)을 사용하세요
FILE_TOO_LARGE	400	업로드된 파일이 10 MB 크기 제한을 초과	아니오	파일 크기를 줄이거나 작은 문서로 분할하세요
MAX_KEYS_REACHED	400	최대 10개의 활성 API 키에 도달	아니오	새 키를 생성하기 전에 사용하지 않는 키를 폐기하세요
USAGE_LIMIT_EXCEEDED	429	월간 추출 한도에 도달	아니오	플랜을 업그레이드하거나 다음 청구 기간까지 기다리세요
INTERNAL_ERROR	500	예기치 않은 서버 오류	예	지수 백오프로 재시도하세요. 지속되면 지원팀에 문의하세요
NOT_CONFIGURED	501	필요한 서버 측 서비스가 구성되지 않음	아니오	지원팀에 문의하세요 -- 서버 구성 문제입니다
EXTRACTION_FAILED	502	AI 추출 처리 실패	예	재시도하세요 -- 일시적인 문제일 수 있습니다. PDF가 유효하고 읽을 수 있는지 확인하세요
EXTRACTION_PARSE_ERROR	502	AI가 JSON으로 파싱할 수 없는 응답을 반환	예	재시도하세요 -- AI가 후속 시도에서 유효한 출력을 생성할 수 있습니다

재시도 가능한 오류

다음 오류 코드만 재시도해야 합니다:

• INTERNAL_ERROR -- 서버 측의 예기치 않은 실패.
• EXTRACTION_FAILED -- 종종 일시적인 문제로 인한 AI 추출 프로세스 실패.
• EXTRACTION_PARSE_ERROR -- AI가 파싱할 수 없는 형식의 출력을 반환.

재시도 시 1초부터 시작하여 최대 3회까지 지수 백오프를 사용하세요:

시도	지연
1차 재시도	1초
2차 재시도	2초
3차 재시도	4초

3회 재시도 후에도 요청이 여전히 실패하면 오류를 기록하고 사용자 또는 모니터링 시스템에 표시하세요.

완전한 재시도 로직 구현 가이드는 오류 처리를 참조하세요.

HTTP 상태 코드 요약

상태	의미
200	성공 -- 요청이 성공적으로 완료됨
400	잘못된 요청 -- 유효성 검사 오류, 잘못된 파일 형식, 파일 크기 초과 또는 키 한도 도달
401	인증되지 않음 -- 인증 실패 (토큰이 누락, 유효하지 않거나 만료됨)
403	금지됨 -- 인증되었지만 요청된 리소스에 대한 권한이 없음
404	찾을 수 없음 -- 요청된 리소스가 존재하지 않음
429	너무 많은 요청 -- 월간 추출 사용 한도 초과
500	내부 서버 오류 -- 서버 측의 예기치 않은 실패
501	구현되지 않음 -- 필요한 서버 측 서비스가 구성되지 않음
502	잘못된 게이트웨이 -- AI 추출 또는 파싱 실패