Docs에러 코드

에러 코드 (Errors)

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

에러 응답 형식

모든 에러 응답은 다음 구조를 따릅니다:

JSON

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

HTTP 상태 코드

성공 코드

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

클라이언트 오류

코드	상태	설명
`400`	Bad Request	잘못된 요청 형식 (예: 잘못된 날짜 포맷, 잘못된 IPC 코드, 알 수 없는 `applicant_match`).
`401`	Unauthorized	누락되었거나 유효하지 않은 API 키. `X-API-Key` 헤더를 확인하세요.
`403`	Forbidden	API 키가 비활성화되었습니다.
`422`	Unprocessable Entity	요청 검증 실패 (필수 필드 누락 또는 잘못된 타입/값).
`429`	Too Many Requests	월 검색 한도를 초과했거나 분당 60회 rate limit에 도달했습니다. 플랜 업그레이드 또는 다음 결제일 리셋까지 대기하세요.

서버 오류

코드	상태	설명
`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: psk_live_... 헤더가 포함되어 있는지 확인하세요.

비활성화된 API 키

403 Forbidden

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

키는 존재하지만 비활성화된 상태입니다. 새 키 발급은 문의를 통해 요청하세요.

월 검색 한도 초과

429 Too Many Requests

{
"detail": "Daily limit exceeded (30/30). Upgrade your plan at https://findip.ai/pricing"
}

검색 한도에 도달했습니다. 한도는 결제일 기준 매월 자동으로 리셋됩니다. 상세조회·도면·번호조회는 카운팅하지 않습니다. 사용량 대시보드에서 현황을 확인하세요.

요청 검증 오류

422 Unprocessable Entity

{
"detail": "query field required"
}

필수 필드가 누락되었거나 타입/값이 올바르지 않습니다. Search API의 요청 스키마를 확인하세요.

잘못된 파라미터

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" 여부를 확인하세요.
적절한 요청 타임아웃을 설정하세요 (검색은 30초, 그 외 엔드포인트는 10초 권장).

인증 (Auth)Next: 개발자 가이드