認証・レート制限・エラー
APIキーの取得方法、リクエストへの設定方法、Rate Limiting、代表的なHTTPエラー形式をまとめます。
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 を利用してください。
Widget認証
Bank Branch Selector Widget は、API Key ではなく Public Client の Public Key を使います。Public Key を public-key 属性に設定すると、Widget が短期 access token の取得と銀行・支店候補の取得を自動で行います。
Public Key は、ダッシュボードの Public Client 画面から作成・取得できます。API Key はサーバーサイド連携用の秘密情報です。ブラウザには API Key を埋め込まないでください。
Widget の導入方法は Bank Branch Selector Widget の認証 を参照してください。
レート制限（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ステータスページ を確認してください。