Docs에러 코드

에러 코드 (Errors)

Findip API는 표준 HTTP 상태 코드를 사용하며, 문제 원인에 대한 세부 정보를 포함한 JSON 에러 응답을 반환합니다.

에러 응답 형식

대부분의 에러 응답은 다음 구조를 따릅니다:

JSON

{
"detail": "사람이 읽을 수 있는 오류 메시지"
}

단, 422 요청 검증 오류만은 detail 이 문자열이 아니라 필드별 오류 객체의 배열입니다. detail 을 문자열로 단정하지 말고 타입을 확인한 뒤 처리하세요.

HTTP 상태 코드

성공 코드

코드	상태	설명
`200`	OK	요청이 성공했습니다.

클라이언트 오류

코드	상태	설명
`400`	Bad Request	잘못된 요청 형식 (예: 잘못된 날짜 포맷, 4자리 미만 IPC 코드, `query`·`image_url`·`sequence` 를 모두 누락).
`401`	Unauthorized	누락되었거나 유효하지 않은 API 키. `X-API-Key` 헤더를 확인하세요.
`403`	Forbidden	API 키가 비활성화되었습니다.
`422`	Unprocessable Entity	요청 검증 실패 (필수 필드 누락 또는 잘못된 타입/값).
`429`	Too Many Requests	검색 크레딧이 부족하거나 분당 60 API 요청 제한에 도달했습니다. 플랜을 업그레이드하시거나, 유료 플랜은 다음 결제일의 리셋을 기다려 주세요.

서버 오류

코드	상태	설명
`500`	Internal Server Error	서버에서 예기치 않은 오류가 발생했습니다 (임베딩 실패 포함). 잠시 후 다시 시도하세요.
`503`	Service Unavailable	서버를 일시적으로 사용할 수 없습니다 (점검, 과부하, 또는 인증 서비스 장애).

자주 발생하는 에러 상황

API 키 누락 또는 잘못됨

401 Unauthorized

{
"detail": "Missing X-API-Key header"
}

401 Unauthorized

{
"detail": "Invalid API key"
}

요청에 X-API-Key: pmk_live_... 헤더가 포함되어 있는지 확인하세요.

비활성화된 API 키

403 Forbidden

{
"detail": "API key is deactivated"
}

키는 존재하지만 비활성화된 상태입니다. 계약 고객은 대시보드의 API 키 화면에서 새 키를 발급하실 수 있습니다.

검색 크레딧 부족

사용하지 않은 검색 크레딧은 다음 주기로 이월되지 않습니다. 검색 크레딧은 현금 가치가 없고 다른 계정으로 양도할 수 없습니다. 서버가 수락한 텍스트 검색은 1 크레딧, 이미지(도면)·서열 검색과 트렌드 분석은 2 크레딧을 사용하며, 상세조회·도면·번호조회는 0 크레딧입니다. LLM이 답변 하나를 위해 검색을 여러 번 실행하면 수락된 검색별로 각각 차감합니다. 작업별 단가는 인증 문서의 표를 참고하세요.

분당 API 요청 제한은 크레딧과 별도로 요청 수를 계산하며, 0 크레딧 호출도 포함합니다. 백엔드 버전에 따라 detail 문구와 선택 메타 필드는 달라질 수 있으므로 클라이언트는 메시지 문자열이 아니라 HTTP 429 상태를 기준으로 처리해야 합니다. 사용량 대시보드에서 크레딧 현황을 확인하세요.

요청 검증 오류

422 Unprocessable Entity

{
"detail": [
  {
    "type": "string_type",
    "loc": ["body", "query"],
    "msg": "Input should be a valid string",
    "input": 123
  }
]
}

타입이나 값이 스키마와 맞지 않습니다. loc 이 문제가 된 필드 경로를, msg 가 사유를 알려 줍니다. Search API의 요청 스키마를 확인하세요.

정의되지 않은 필드를 보내는 것은 오류가 아닙니다 — 서버가 조용히 무시하고 200 을 반환하므로, 파라미터 이름의 오타는 에러가 아니라 필터가 걸리지 않은 결과로 나타납니다.

잘못된 파라미터

400 Bad Request

{
"detail": "invalid date: '2024/01/01' (expected YYYY-MM-DD)"
}

특허 상세 조회의 항목별 not_found

POST /api/v1/patents/details 는 일부 ID 를 찾지 못하더라도 200 OK 를 반환합니다. 확인되지 않은 ID 는 최상위 오류가 아니라 patents 배열 안에 {"patent_id": "...", "error": "not_found"} 형태로 나타납니다. 각 항목을 개별적으로 확인하세요.

200 OK (partial)

{
"patents": [
  { "patent_id": "KR1020230012345A", "metadata": { ... }, "content": "..." },
  { "patent_id": "US99999999B2", "error": "not_found" }
]
}

오류 처리 모범 사례 (Best Practices)

응답 본문(body)을 파싱하기 전에 항상 HTTP 상태 코드를 먼저 확인하세요.
429 및 500 에러 발생 시, 지수 백오프(Exponential Backoff) 알고리즘을 적용해 재시도하세요.
디버깅을 위해 전체 에러 응답을 로깅하세요. detail 필드에 원인 파악을 위한 주요 정보가 들어 있습니다.
POST /api/v1/patents/details 의 경우 200 응답이라도 각 항목의 error: "not_found" 여부를 확인하세요.
적절한 요청 타임아웃을 설정하세요. 검색은 보통 2–6초에 끝나지만 여유를 두어 30초를, 상세조회·도면·커버리지 등 그 외 엔드포인트는 10초를 권장합니다.

인증 (Auth)