エラーとステータスコード

finlight API は、リクエストの結果を示すために一般的な HTTP ステータスコードを使用します。2xx は成功、4xx はリクエストが拒否されたこと（通常は修正可能なもの）、5xx は当社側の問題を意味します。各エラーは、何が問題だったかを説明する JSON ボディを返します。

注: REST および WebSocket リクエストは X-API-KEY ヘッダーで認証します。キーが欠落または無効な場合は 401 が返ります。（Webhook の配信認証 —finlight があなたのエンドポイントに送信するヘッダー— は別物です。Webhook 認証を参照してください。）

ステータスコード一覧

400 — Bad Request

クエリパラメータまたはリクエストボディが検証に失敗した場合、あるいは query 文字列が無効なフィールドレベル構文を使用している場合に返ります。

無効なパラメータ:

{
  "statusCode": 400,
  "message": ["pageSize must not be greater than 100"],
  "error": "Bad Request"
}

無効な query 構文（POST /v2/articles）:

{
  "statusCode": 400,
  "message": [
    {
      "property": "query",
      "constraints": { "query": "Invalid query syntax near 'ticker:'" }
    }
  ],
  "error": "Bad Request"
}

正しい query 構文については高度なクエリの構築を参照してください。

401 — Unauthorized

X-API-KEY ヘッダーが欠落しているか、形式が不正か、有効なキーではありません。

{
  "statusCode": 401,
  "message": "Unauthorized"
}

finlight ダッシュボードでキーを取得または再発行してください。

403 — Forbidden

リクエストは認証されていますが、プランに要求された機能が含まれていません。例えば、フル記事コンテンツを含まないプランでそれを要求した場合などです。

{
  "statusCode": 403,
  "message": "Your subscription does not allow calling the extended article content"
}

各プランに含まれる機能についてはレート制限とクォータを参照してください。

404 — Not Found

要求されたリソースが存在しません。最も多いのは、finlight が索引していない link を指定した GET /v2/articles/by-link です。

{
  "statusCode": 404,
  "message": "Article not found"
}

422 — Unprocessable Entity

一部のエンドポイントはグローバルバリデータで検証し、フィールドをキーとするエラーマップを返します。各キーは問題のあったフィールドで、値は失敗した制約を列挙します。

{
  "status": 422,
  "errors": {
    "language": "language must be a string"
  }
}

注: 検証の失敗は、ルートに応じて 400（記事エンドポイント）または 422（グローバルバリデータ）として現れることがあります。いずれも不正なリクエストを示します。どのフィールドが失敗したかはボディを確認してください。

429 — Too Many Requests

使用制限を超過しました。それぞれ特定のメッセージを持つ、2 つの異なるケースがあります。

月間リクエストクォータの超過:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded token limit of 5000 for the current period."
}

バースト（短期）レートの超過:

{
  "statusCode": 429,
  "message": "Throttling Exception: Exceeded rate limit of 10 requests per 10 seconds."
}

注: finlight は現在、Retry-After やレート制限ヘッダーを返しません。バーストの 429 の場合は、約 10 秒待ってから再試行してください。月間クォータの 429 の場合は、次の請求期間の開始時（またはアップグレード後）にリクエストが再び成功します。レート制限とクォータを参照してください。

500 — Internal Server Error

finlight 側で予期しないエラーが発生しました。これらは一時的なものです。バックオフして再試行し、問題が続く場合はサポートからご連絡ください。

{
  "statusCode": 500,
  "message": "Internal server error"
}

エラーを適切に処理する

• まずステータスコードを確認し、次に詳細について JSON ボディを読みます。
• 4xx（429 を除く）はあなたのバグです。リクエストを修正してください。変更せずに再試行しても解決しません。
• 429 と 5xx は再試行可能です。指数バックオフを使用してください。バーストの 429 なら約 10 秒で十分です。
• WebSocket のエラーは HTTP ステータスではなく、ソケット上の error サーバーメッセージとして届きます。WebSocket の基礎を参照してください。
• Webhook の配信失敗（あなたのエンドポイントへの）は、同期的に返されるのではなくダッシュボードで追跡されます。Webhook のテストを参照してください。