Docsエラーコード

エラーコード (Errors)

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

エラーレスポンスの形式

ほとんどのエラーレスポンスは次の構造に従います。

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

ただし 422 リクエスト検証エラーだけは、detail が文字列ではなくフィールド単位のエラーオブジェクトの配列になります。detail を文字列と決めつけず、型を確認してから処理してください。

HTTP ステータスコード

成功

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

クライアントエラー

コードステータス説明
400Bad Request不正なリクエスト形式(例: 不正な日付形式、4 文字未満の IPC コード、query・image_url・sequence をすべて省略)。
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: pmk_live_... ヘッダが含まれているかご確認ください。

無効化された API キー

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

キーは存在しますが無効化されています。ご契約のお客様は、ダッシュボードの API キー 画面から新しいキーを発行していただけます。

検索クレジット不足

未使用の検索クレジットは次の周期に繰り越されません。検索クレジットに現金価値はなく、他のアカウントへ譲渡できません。サーバーが受け付けたテキスト検索は1クレジット、画像（図面）検索・配列検索とトレンド分析は2クレジット、詳細・図面・番号照会は0クレジットです。LLMが1つの回答のために複数回検索すると、受け付けられた検索ごとにクレジットを使用します。操作ごとの単価は 認証 の表をご参照ください。

1分あたりの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" }
]
}

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

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