Docsエラーコード

エラーコード (Errors)

FindIP API は標準 HTTP ステータスコードを使用し、原因の詳細を含む JSON エラーレスポンスを返します。

エラーレスポンスの形式

すべてのエラーレスポンスは次の構造に従います。

JSON
{
"detail": "人が読めるエラーメッセージ"
}

HTTP ステータスコード

成功

コードステータス説明
200OKリクエスト成功。

クライアントエラー

コードステータス説明
400Bad Request不正なリクエスト形式(例: 不正な日付形式、不正な IPC コード、未知の applicant_match)。
401UnauthorizedAPI キーの欠落または無効。X-API-Key ヘッダをご確認ください。
403ForbiddenAPI キーが無効化されています。
422Unprocessable Entityリクエスト検証に失敗(必須フィールドの欠落、型/値の誤り)。
429Too Many Requests月間検索枠を超過、もしくは 1 分あたり 60 回のレート制限に到達しました。プランのアップグレードもしくは次回請求日までお待ちください。

サーバーエラー

コードステータス説明
500Internal Server Error予期せぬサーバー側エラーが発生しました(埋め込み失敗を含む)。少し時間をおいてから再試行してください。
503Service 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" }
]
}

エラー処理のベストプラクティス

  1. レスポンスボディをパースする前に必ず HTTP ステータスコードを確認してください。
  2. 429・500 時は指数バックオフ (Exponential Backoff) でリトライしてください。
  3. デバッグのため、エラーレスポンス全体をログに残してください。detail フィールドに原因特定の主要情報が入ります。
  4. POST /api/v1/patents/details では、200 レスポンスでも各項目の error: "not_found" を確認してください。
  5. 適切なリクエストタイムアウトを設定してください (検索は 30 秒、その他は 10 秒推奨)。
認証 (Auth)Next: 開発者ガイド
APIエラーコード — 特許検索API | FindIP