エラーとレート制限

エラー形式

エラーは HTTP ステータスコードと JSON ボディで返します。ボディは全エンドポイント共通で、機械可読な code を含みます。

{ "error": { "code": "not_found", "message": "Security not found" } }

401 には WWW-Authenticate: Bearer が付きます（トークンが無効な場合は error="invalid_token"、スコープ不足の 403 は error="insufficient_scope"）。

ステータス	意味
`400`	パラメータ不正（不正だったパラメータは `error.details` に記載）
`401`	API キーが無い・無効
`404`	リソースが存在しない（例: 存在しない証券コードの指定）
`429`	レート制限・日次上限の超過
`5xx`	サーバーエラー

`error.code` 一覧

`code`	ステータス	意味
`invalid_parameter`	`400`	パラメータの値が不正。内訳は `error.details`
`invalid_cursor`	`400`	`cursor` が壊れている。前回のレスポンスから取り直すか、先頭から取得し直す
`unauthorized`	`401`	API キーが無い・無効
`forbidden`	`403`	この API キーでは REST API を利用できない
`connect_access_required`	`403`	IRBANK Connect の利用許可が無い（本人確認が未完了・取り消し済み）
`not_found`	`404`	リソースが存在しない
`method_not_allowed`	`405`	そのパスで許可されていない HTTP メソッド
`payload_too_large`	`413`	リクエストが大きすぎる
`rate_limited`	`429`	レート制限・日次上限の超過
`data_unavailable`	`503`	データを一時的に取得できず応答を組み立てられない。バックオフして再試行する
`service_unavailable`	`503`	一時的に利用できない
`internal_error`	`5xx`	サーバーエラー

パラメータ不正（`400`）の詳細

400 では、不正だったパラメータを error.details に列挙します。複数のパラメータが同時に不正な場合は、そのすべてが並びます。

{
  "error": {
    "code": "invalid_parameter",
    "message": "years must be <= 30",
    "details": [{ "param": "years", "reason": "out_of_range", "expected": "<= 30" }]
  }
}

フィールド	内容
`param`	不正だったクエリ／パスパラメータ名
`reason`	不正の種別（下表）。分岐はこの値で書いてください
`expected`	受理される値の要約。示せない場合は省略されます

reason は次の値のいずれかです。値が追加されることはありません。

`reason`	意味
`missing`	必須のパラメータが指定されていない
`conflict`	同時に指定できないパラメータを併用している
`invalid_type`	型が違う（整数を求める箇所に小数、など）
`invalid_format`	形式が違う（`YYYY/MM` でない、コードの桁数が違う、など）
`out_of_range`	許容範囲の外（`expected` に超えた側の境界が入ります）
`unknown_value`	受理される値の集合にない（`expected` に一覧が入ります。大文字小文字は区別します）
`too_many_items`	指定できる件数の上限を超えている
`invalid`	上記のいずれにも当てはまらない

message は人間向けの説明で、文言は予告なく変わります。プログラムからの分岐には error.code と details[].reason を使ってください。

details は、パラメータの検証で弾かれた 400 に載ります。認証やレート制限のようにリクエスト本体に到達する前の段階で返る 400 には載りません。無い場合を許容する実装にしてください。

レート制限と日次上限

日次上限はプランごとに異なります（プランと利用上限）
日次上限は REST API と MCP（IRBANK Connect）で共有の 1 つの枠です。MCP でのリクエストも同じ上限を消費します
日次上限とは別に、短時間の集中アクセスを制御するレート制限があります。現在はアカウントごとに 60 リクエスト/分 です（同一アカウントの複数の API キーで合算されます）。日次上限の残りがある場合でも、この制限を超えたリクエストは 429 Too Many Requests を返します
レート制限値はベータ期間中のため、実際の利用状況を踏まえて調整する場合があります
429 レスポンスには再試行可能時刻を判断できる情報が含まれます
残りリクエスト数は GET /v1/usage で確認できます（この照会自体は日次上限を消費しません）

リトライの指針

429 / 5xx は指数バックオフでリトライしてください。400 / 404 はリクエストを修正しない限り結果が変わらないため、リトライしないでください。

200 でもデータが 0 件のときは reason.code で判断します（詳細は日付・タイムゾーン・欠損値）。

`reason.code`	リトライ
`no_results`	不要（TDnet 由来の直近開示分のみ、24 時間後に追加されることがあります）

サーバー側が一時的に回答を返せない場合は 200 ではなく 503 + {"error": {"code": "data_unavailable", ...}} を返すので、指数バックオフでリトライしてください。