---
title: エラーとレート制限
sidebar:
  order: 7
---

## エラー形式

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

```json
{ "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` に列挙します。複数のパラメータが同時に
不正な場合は、そのすべてが並びます。

```json
{
  "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` には載りません。**無い場合を許容する実装**に
してください。

## レート制限と日次上限

- 日次上限はプランごとに異なります（[プランと利用上限](/getting-started/plans)）
- 日次上限は 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` で判断します（詳細は[日付・タイムゾーン・欠損値](/guides/dates-and-nulls)）。

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

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