認証・レート制限・エラー
APIキーの取得方法、リクエストへの設定方法、Rate Limiting、代表的なエラー形式をまとめます。
APIキーの取得
APIキーは BankcodeJP API のダッシュボードから取得できます。アカウント作成後、ダッシュボードにログインし、APIキーを確認してください。
リクエストにAPIキーを設定する
APIキーは、クエリパラメータまたはHTTPヘッダーで指定できます。サーバーサイド実装では、ログやRefererへの露出を避けるため x-api-key ヘッダーでの指定を推奨します。
推奨: HTTPヘッダーで指定する
curl "https://apis.bankcode-jp.com/v3/banks" -H "x-api-key: YOUR_API_KEY"クエリパラメータで指定する
curl "https://apis.bankcode-jp.com/v3/banks?apikey=YOUR_API_KEY"クエリパラメータ名は apikey または apiKey を利用できます。HTTPヘッダーでは x-api-key を利用してください。
レート制限（Rate Limiting）
BankcodeJP API では、プランごとにリクエスト回数およびリクエストレートの制限があります。制限に到達した場合、APIは 429 Too Many Requests を返します。
レート制限には、一定期間内の総リクエスト数に対する制限と、短時間に集中するリクエストに対する制限があります。連続リクエストを行う場合は、クライアント側でリトライ間隔を設けてください。
レスポンスヘッダー
レスポンスには、レート制限に関するヘッダーが含まれる場合があります。ヘッダー名や値は、対象APIやGateway設定により異なる場合があります。
RateLimit-Limit: 1
RateLimit-Remaining: 0
RateLimit-Reset: 1
X-RateLimit-Limit-Minute: ...
X-RateLimit-Remaining-Minute: ...Remaining が 0 の場合、次のリセットまで追加リクエストが制限される可能性があります。
代表的なエラー
| Status | 意味 | 主な原因 |
|---|---|---|
| 400 | 不正なリクエスト | URLエンコード漏れ、クエリ構文不正など。 |
| 401 | 認証エラー | APIキー未指定または不正。 |
| 403 | 権限なし | プランまたはACLにより拒否。 |
| 404 | リソースなし | 存在しない金融機関コード、支店コード、パス。 |
| 422 | バリデーションエラー | Resolve APIなどで必須項目不足、enum不正など。 |
| 429 | レート制限超過 | 日次上限または秒間レート制限の超過。 |
| 5xx | サーバー側エラー | 一時的な障害または内部エラー。 |
エラーレスポンス形式
Search API と Resolve API では、エラー発生箇所によりレスポンス形式が異なる場合があります。クライアント実装では、HTTPステータスコードを主として扱い、レスポンス本文は補助情報として扱ってください。
Resolve API: 401 Unauthorized
{
"message": "Unauthorized",
"request_id": "39a4cc3e552b6422c3226f6ebb7f382b"
}Resolve API: 422 Validation Error
{
"detail": [
{ "type": "missing", "loc": ["body", "bank_name"], "msg": "Field required", "input": {} },
{ "type": "missing", "loc": ["body", "branch_name"], "msg": "Field required", "input": {} }
],
"request_id": "0ec2d9e1fd04463890ee6a787ad56e99"
}429 Too Many Requests
HTTP/2 429
content-type: application/json
{
"message": "API rate limit exceeded"
}429の本文はGateway設定により異なる場合があります。実装ではHTTPステータスコードとレート制限ヘッダーを優先してください。
稼働状況
最新の稼働状況は APIステータスページ を確認してください。