エラーとステータスコード
このページは、ローン領域 API のすべてのルートで使用されるレスポンスエンベロープをまとめたリファレンスです。ルートごとのドキュメントには、そのルートが返すステータスコードが記載されています。このページでは、各エンベロープの形と、受け取る可能性のある名前付き code 値のカタログを記載します。
連携の前に一度通読し、予期しない 2xx 以外のステータスが返されたときに参照してください。
ステータスコードのカタログ
| ステータス | 発生する場面 | ルートの例 |
|---|---|---|
200 OK | 読み取りの成功、冪等なリプレイ、ソフト取り消し、一括バッチの処理完了、ステータス遷移。 | 作成以外のすべてのルート。 |
201 Created | 単一レコードのルートでの初回作成の成功。 | POST /borrowers。 |
202 Accepted | 非同期インポートの開始。処理はバックグラウンドで続行されます。 | POST /imports。 |
204 No Content | 現在、どのローン領域ルートも返しません。 | — |
400 Bad Request | リクエストの検証エラー:JSON の形式不正、クエリの形式不正、スキーマ違反。 | すべての変更系ルート。 |
401 Unauthorized | Authorization ヘッダーがない、トークンが未知、またはトークンが失効しています。 | すべてのルート。 |
403 Forbidden | 呼び出し元が投資家アカウントです。投資家はモニタリングデータ API を使用できません(MONITORING_INVESTOR_FORBIDDEN)。管理者以外による ?unmask=true は 403 を返さず、PII をマスキングした 200 を返します。 | すべてのルート。 |
404 Not Found | リソースが存在しないか、他の組織に属しています。 | リソースを参照するすべてのルート。 |
409 Conflict | この id を持つ有効な行がすでに存在する、Idempotency-Key が別のステータス遷移に再利用された、またはコミットの段階でアップロードされたファイルが見つかりませんでした。 | POST /borrowers、PATCH /loans/.../status、POST /imports/{id}/commit。 |
413 Payload Too Large | 一括 NDJSON のバッチが行数またはバイト数の上限を超えています。 | POST /bulk/{entity}。 |
422 Unprocessable Entity | 参照先の行が同じポートフォリオ内に有効なものとして存在しない(REFERENCED_ENTITY_NOT_FOUND)、または要求されたステータス遷移が遷移マトリクスにありません(INVALID_STATUS_TRANSITION)。検証エラーには 400 が使われます。 | POST /loans、POST /payments、PATCH /loans/{loanRef}/status。 |
429 Too Many Requests | レート制限を超えました。プラットフォームは組織ごとのレート制限を適用します。レスポンスヘッダー Retry-After が秒数を示します。 | すべてのルート。 |
500 Internal Server Error | 処理されなかったプラットフォームのエラー。一時的なものとして扱ってください。同じ Idempotency-Key で安全に再試行できます。 | すべてのルート。 |
429 以外の 4xx はすべてリクエストの不備として扱い、クライアントロジックでは再試行せずに入力を拒否してください。429 と 500 は一時的なものとして扱い、バックオフを入れて再試行してください。Idempotency-Key があれば再試行は安全です。
標準エンベロープ
ローン領域 API は、成功以外のステータスコードに 3 種類のレスポンスエンベロープを使用します。エンベロープの形から、どのような種類の失敗かがわかります。
検証エンベロープ — 400 Bad Request
スキーマ違反、クエリパラメーターの形式不正、パスの形式不正に使用されます。
{
"error": "Validation failed",
"fieldErrors": [
{ "path": "interestRateApr", "message": "interestRateApr must be >= 0" },
{ "path": "termMonths", "message": "termMonths must be > 0" }
]
}| フィールド | 型 | 備考 |
|---|---|---|
error | string | 人が読める短い要約。 |
fieldErrors[].path | string | 問題のあるフィールドへのドット区切りのパス。(root) はボディそのものを示します(JSON の解析に失敗した場合など)。 |
fieldErrors[].message | string | 人が読める説明。 |
一部のルートは、クエリパラメーターのエラーに対して fieldErrors[] ではなく errors[] を返します(フレームワークの慣例がインターフェースによって異なるためです)。path/message の形は同一なので、解析の際は 2 つの配列名を同じものとして扱ってください。
名前付きコードのエンベロープ — 4xx
失敗に、プラットフォームが安定した code 値で名付けた具体的な原因がある場合に使用されます。fieldErrors の有無は任意で、失敗を特定のフィールドに結び付けられるかどうかによります。
{
"error": "a borrower with this id already exists",
"code": "ID_CONFLICT",
"fieldErrors": [
{ "path": "id", "message": "a borrower with this id already exists" }
]
}| フィールド | 型 | 備考 |
|---|---|---|
error | string | 人が読める要約。 |
code | string | 安定した機械可読のコード。用語集を参照してください。 |
fieldErrors[] | array | absent | 失敗が特定のフィールドを指す場合に存在します。 |
一部のエンベロープには、追加の構造化されたコンテキストが含まれます。たとえば batch_too_large には、超過した上限を示す fieldErrors ブロックが含まれます。これらはルートごとのドキュメントに記載しています。
簡易エラーエンベロープ — 404 / 401
追加のコンテキストが呼び出し元の役に立たない、簡潔なレスポンスに使用されます。典型的な例は 404 です。
{ "error": "Not found" }一部のルートは { "error": "...", "code": "NOT_FOUND" } を返します。404 における code の有無は参考情報として扱い、それに依存しないでください。
2 つのコード空間:大文字と小文字
ローン領域 API は、取り込み方式によって意図的に分けられた 2 つの異なる code 名前空間を使用します。
- 単一レコードのルート(POST、PATCH、取り消し、照合の GET)は
UPPER_CASEのコード値を返します:ID_CONFLICT、PORTFOLIO_NOT_FOUND、REFERENCED_ENTITY_NOT_FOUND、INVALID_STATUS_TRANSITION、CHECK_VIOLATION、NOT_FOUND、UNKNOWN_KIND、COMMIT_FAILED、IDEMPOTENCY_CONFLICT、IDEMPOTENCY_KEY_REUSED、MONITORING_INVESTOR_FORBIDDEN。一括 NDJSON のルートもMONITORING_INVESTOR_FORBIDDENを大文字で返します。 - 一括 NDJSON のルートは
lower_caseのコード値を返します:batch_too_large、portfolio_not_found、portfolio_id_required、invalid_body、invalid_json、および後述の行単位のコード。
クライアントで code によって分岐する際は、大文字・小文字を正確に一致させてください。2 つのコード空間はそれぞれ独立して安定しています。正規化しないでください。
エラーコード用語集
プラットフォームは、名前付きの失敗パターンそれぞれに安定した code を付けます。プログラムでの分岐にはこれらを使用してください。error メッセージの文言は変わる可能性があります。
単一レコードのコード空間
| コード | ステータス | 返すルート | 発生条件 |
|---|---|---|---|
ID_CONFLICT | 409 | POST /borrowers、POST /loans、POST /payments。 | 同じ id を持つ有効な行がすでに存在します。 |
PORTFOLIO_NOT_FOUND | 404 | すべての単一レコード書き込みルート。 | ボディの portfolioId が貴組織内に存在しません。 |
REFERENCED_ENTITY_NOT_FOUND | 422 | POST /loans、POST /payments。 | borrowerId または loanId が、同じポートフォリオ内に有効なものとして存在しない行を参照しています。 |
INVALID_STATUS_TRANSITION | 422 | PATCH /loans/{loanRef}/status。 | 遷移元と遷移先のステータスの組み合わせが遷移マトリクスにありません。 |
IDEMPOTENCY_CONFLICT | 409 | PATCH /loans/{loanRef}/status。 | この Idempotency-Key は別のステータス遷移ですでに使用されています。新しい遷移は新しいキーで送信してください。 |
IDEMPOTENCY_KEY_REUSED | 409 | POST /imports。 | この Idempotency-Key は、リクエストパラメーター(kind、filename、sizeBytes など)が異なるインポートですでに使用されています。レスポンスには importId と mismatchedFields が含まれます。新しいインポートは新しいキーで送信してください。 |
MONITORING_INVESTOR_FORBIDDEN | 403 | 一括 NDJSON を含む、モニタリングのすべてのローン関連ルート。 | 呼び出し元が投資家アカウントです。投資家はモニタリングデータ API を使用できません。 |
CHECK_VIOLATION | 400 | POST /payments。 | データルールに違反しました(通常は債務免除の不変条件です。スキーマ層が検証時に同じ形を先に拒否します)。 |
NOT_FOUND | 404 | GET /borrowers/{id}、GET /payments/{id}、PATCH /loans/.../status、POST /payments/{id}/cancel、GET /loans/{externalId}。 | 検索対象の行が指定した範囲に有効なものとして存在しない、または他の組織に属しています。 |
UNKNOWN_KIND | 400 | POST /imports。 | kind が 6 つのローン種類のいずれでもありません。レスポンスには allowed 配列が含まれます。 |
COMMIT_FAILED | 409 | POST /imports/{id}/commit。 | プラットフォームがアップロードされたファイルを見つけられませんでした。通常はアップロードが完了していません。アップロードを再試行してから、再度コミットしてください。 |
一括 NDJSON のコード空間
| コード | ステータス | 発生条件 |
|---|---|---|
batch_too_large | 413 | ボディが 10 000 行または 10 MB を超えています。行数上限かバイト数上限かは error と fieldErrors[].message で区別します。 |
portfolio_id_required | 400 | ?portfolioId=<UUID> が欠落しているか、有効な UUID ではありません。 |
portfolio_not_found | 404 | ?portfolioId= が貴組織内に有効なものとして存在しません。 |
invalid_body | 400 | リクエストボディをテキストとして読み取れませんでした。 |
invalid_json | (行単位) | 行が有効な JSON ではありません。行単位の errors[] 配列内に現れ、バッチは 200 を返します。 |
この用語集にないコードは、このページの最終改訂以降にプラットフォームが新しい名前付きコードを追加したことを示します。エンジニアリングチームが関連付けられるよう、code の値は必ずアプリケーションのエラーとともにそのまま記録してください。
行単位のエラーコード(一括と非同期インポート)
一括 NDJSON と非同期インポートはどちらも行単位のエラーを返します。一括インターフェースは 1 組の値を使用し、非同期インポートのインターフェースは似ているものの少し異なる値の組を使用します(特に、validation_failed ではなく validation_error を含んでおり、これは旧来のインターフェースであることを反映しています)。行単位のエントリが表すのは、成功したバッチ内の個々の行の失敗であり、エンベロープレベルの失敗ではありません。
一括 NDJSON の行単位のコード
| 行単位のコード | 発生条件 |
|---|---|
validation_failed | 行がスキーマ検証に失敗しました。message フィールドに検証エラーが含まれます。 |
fk_violation | 行内の外部キー参照(例:borrowerId、loanId)が、同じポートフォリオ内の有効な行に解決されません。 |
unique_violation | 同じ (portfolio, externalId) または id を持つ有効な行がすでに存在します(行単位の id_conflict コードは別途存在せず、どちらの種類の呼び出し元 ID の衝突もここに現れます)。 |
check_violation | データルールに違反しました。通常は返済における債務免除ルールです。 |
db_error | この行の保存中に予期しないエラーが発生しました。行は失敗として報告され、バッチは続行されます。 |
invalid_json | 行が有効な JSON ではありませんでした。プラットフォームはバッチの残りを処理します。 |
非同期インポートの行単位のコード
| 行単位のコード | 発生条件 |
|---|---|
parse_error | 行が有効な JSON ではありませんでした。 |
validation_error | 行がスキーマ検証に失敗しました。 |
portfolio_mismatch | 行の portfolioId がインポートの基準ポートフォリオと一致しません。 |
processor_error | この行の処理中にハンドラーが予期せず失敗しました。 |
行の保存中のエラー(参照先の欠落、重複、データルール違反)は、上記のいずれかのコードで現れ、詳細は errorMessage に記載されます。
行単位のエラーが、一括インターフェースのトップレベルで 200 以外のレスポンスになることはありません。リクエスト自体が正しい形式であればバッチ全体としては成功であり、行単位のコードが何が取り込まれたかを示します。
再試行のセマンティクス
変更系ルートで安全に再試行するためのパターンは次のとおりです。
- 論理的な操作ごとに決定的な
Idempotency-Keyを生成します。UUIDv4 にルートの識別子を付けたもので十分です。 - そのキーを付けてリクエストを送信します。
2xx、409 ID_CONFLICT、409 IDEMPOTENCY_CONFLICT、409 IDEMPOTENCY_KEY_REUSED、404、403、400、413、422のいずれかの場合は、再試行しないでください。結果は確定しています。429の場合は、Retry-Afterヘッダーで示された時間が経過してから再試行します。500またはネットワークエラーの場合は、指数バックオフを入れて、少ない固定回数まで再試行します。最初の試行が届いたかどうかにかかわらず、Idempotency-Keyによって再試行は安全です。
成功したリクエストを同じ Idempotency-Key で再試行すると、元のリクエストと同じレスポンスが返され、対象のエンティティには reused: true が付きます。これが、ネットワークの瞬断から復旧するための標準的な正常系の手順です。
プラットフォームが決して返さないもの
運用上のデバッグのために、「返されないもの」を知っておくと役立ちます。
- プラットフォームはどの
5xxステータスコードも仕様として扱いません。500は常に修正すべきバグです。特定の500の形に依存するクライアントロジックは書かないでください。 404レスポンスがテナント情報を漏らすことはありません。 他の組織に存在する行に対する404は、どこにも存在しない行に対する404とまったく同じに見えます。組織をまたいだ存在を推測するクライアントロジックは書かないでください。- 成功レスポンスが
success: falseという名前のボディフィールドを持つことはありません。 呼び出しが成功したかどうかはステータスコードで判断します。詳細はボディの形が担います。 - 書き込みルートが、パスパラメーター形式(「Location」ヘッダー)で自身の UUID を返すことはありません。 作成された UUID はレスポンスボディの
idフィールドに含まれます。