Didit APIエラー：ステータスコード、レスポンス本文、対処法

Didit APIは、失敗をHTTPステータスコードで通知し、ほぼすべての場合にJSONボディを返します。このページでは、各ステータスの意味、ボディの形式、分岐に使えるcodeの値、そして安全に再試行できる失敗について説明します。メッセージの文言は変わる可能性があるため、まずステータスに、そしてcodeがある場合はその値に基づいて処理してください。

ステータスコード

ステータス	意味	対処方法	再試行
`400`	リクエストが無効です。フィールドが検証に失敗したか、画像または書類を読み取れませんでした	ボディに示された内容を修正します	修正後に可
`401`	送信したキーが誤っている、形式が不正、失効済み、または期限切れです	`DIDIT_API_KEY`を確認するか、新しいキーを作成します	修正後に可
`402`	チェックの料金を支払えなかったため、チェックは実行されませんでした	残高をチャージします	チャージ後に可
`403`	キーが送信されていない、キーにこのリソースまたはアクションへのアクセス権がない、リクエストがキーのIPリスト外から送られた、または残高が呼び出しの料金に足りません	ボディを読み、APIキーのエラーとクレジット不足を参照します	修正後に可
`404`	リソースが存在しないか、セッションがキーのワークフローまたはステータスの範囲外です	IDとキーの制限を確認します	不可
`409`	リクエストが現在の状態と競合しています。たとえば`Idempotency-Key`の再利用や、すでに実行済みのステップなどです	`code`を確認し、状態を再取得します	`code`による
`410`	リソースが期限切れです。たとえばセッションや招待などです	新しく作成します	不可
`415`	リクエストボディがJSONではありません	`Content-Type: application/json`を送信します	修正後に可
`422`	ウォレットアドレスが複数のブロックチェーンに該当するため、スクリーニングも課金も行われませんでした	`blockchain`に`candidate_chains`のいずれかを設定して再送信します	修正後に可
`429`	レート制限またはクォータに達しました	`Retry-After`の時間だけ待ちます。レート制限を参照してください	待機後に可
`500`	Didit側で予期しないエラーが発生しました	バックオフを入れて再試行し、続く場合はサポートに連絡します	再試行を参照
`502`	Diditが依存するサービスがエラーを返しました	`code`を確認します	再試行を参照
`503`	Diditが依存するサービスが一時的に利用できません	`code`を確認し、再度試します	再試行を参照

エラーボディ

エラーボディには共通のエンベロープがないため、防御的に読み取ってください。形式はエンドポイントの系統によって異なります。

形式	使われる場面	例
`detail`	認証、見つからないエラー、レート制限を含むほとんどのエラー	`{"detail": "You do not have permission to perform this action."}`
`detail`と`code`	安定したコードを持つエラー	`{"detail": "This application was deleted.", "code": "application_deleted"}`
フィールドエラー	入力の検証	`{"workflow_id": ["This field is required."]}`
`non_field_errors`	複数フィールドにまたがる検証	`{"non_field_errors": ["..."]}`
JSON配列	シミュレーション呼び出しなど、一部の検証エラー	`["Scenario can only be armed before the verification starts."]`
`error`	ほとんどのスタンドアロンAPI	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`error`と`code`	スタンドアロンAPIの画像エラー	`{"error": "...", "code": "invalid_image"}`
`error`がコードで、`detail`を含む形式	デジタルIDウォレットの認証	`{"error": "insufficient_credits", "detail": "..."}`

500にはJSONボディがまったくない場合があるため、解析できないボディも処理できるようにしてください。

const raw = await response.text();
let body = {};
try {
  body = JSON.parse(raw);
} catch {
  // A 5xx response may not be JSON: rely on response.status.
}
const code = body.code ?? null;
const message = body.detail ?? body.error ?? (Array.isArray(body) ? body[0] : raw);

APIキーのエラー

送信した内容	ステータス	`detail`
`x-api-key`ヘッダーなし	`403`	`You do not have permission to perform this action.`
誤っている、形式が不正、または失効済みのキー	`401`	`Authentication credentials were not provided or are invalid.`
期限切れのキー	`401`	`This API key has expired.`
IPリスト外から使用されたキー	`403`	`This API key can't be used from this IP address.`
このリソースまたはアクションへのアクセス権を持たないスコープ付きキー	`403`	`This API key has no access to this endpoint.`
一部のワークフローまたはステータスに制限されたキーを、使用できないエンドポイントで使用した場合	`403`	`This API key only reaches sessions inside its workflow or status limits, so it can't use this endpoint.`
一部のワークフローまたはステータスに制限されたキーを、その制限外のセッションに使用した場合	`404`	`Session not found.`
アプリケーションが削除された直後のキー	`403`	`This application was deleted.`、および`"code": "application_deleted"`

アプリケーションが削除されてから数分間、APIはapplication_deletedで応答し、その後は他の不正なキーと同様にそのキーを拒否します。再試行しないでください。アプリケーションとそのキーはすでに削除されています。キーとその制限の仕組みについては、API認証とAPIキーを参照してください。

クレジット不足

残高不足の通知方法は、APIの系統ごとに異なります。

呼び出し	ステータス	ボディ
`POST /v3/session/`	`400`	`{"detail": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
ほとんどのスタンドアロンAPI	`403`	`{"error": "You don't have enough credits to perform this request. Please top up at https://business.didit.me"}`
`POST /v3/bank/account-check/`	`402`	`{"detail": "...", "code": "insufficient_credits"}`
デジタルIDウォレットの検証	`403`	`{"error": "insufficient_credits", "detail": "..."}`
取引、トラベルルール、住所の検証	`403`	`{"detail": "...", "code": "insufficient_credits"}`

契約をご利用の場合、組織の有料サービスが一時停止されている間、セッション作成リクエストは"code": "contract_billing_suspended"付きの403を返します。サンドボックスアプリケーションは課金されることがないため、これらのチェックは行われません。

エラーコード

これらのcodeの値は変わらないため、処理の分岐に使用できます。ほとんどはdetailと並んで返されます。Digital IDウォレット認証では、コードはerrorの値として返されます。

アクセスと請求

コード	ステータス	意味
`insufficient_credits`	`402`, `403`	残高が呼び出しの料金に足りません
`contract_billing_suspended`	`403`	この組織では有料サービスが一時停止されています
`contract_rate_missing`	`402`, `403`	契約にこのチェックの料金が設定されていません
`application_deleted`	`403`	キーのアプリケーションが削除されています
`organization_deleted`	`403`	キーの組織が削除されています
`event_monitoring_disabled`	`403`	このアプリケーションではイベントの取り込みが有効になっていません
`networks_not_entitled`	`403`	この組織では不正対策ネットワークが有効になっていません

リクエストと冪等性

コード	ステータス	意味
`invalid_image`	`400`	画像を使用できませんでした
`return_url_invalid`	`400`	リターンURLが許可されていません
`idempotency_key_invalid`	`400`	`Idempotency-Key`が255文字を超えています
`idempotency_key_reused`	`409`	このキーは異なるボディですでに使用されています
`idempotency_key_in_progress`	`409`	このキーを使った最初のリクエストがまだ処理中です。`Retry-After`で指定された時間待ってください
`verification_in_progress`	`409`	ユーザーが現在この認証を進めているため、キャンセルできません。`Retry-After`で指定された時間待ってください
`feature_override_not_pending`	`409`	オーバーライドはすでに適用されたか、キャンセルされています

銀行・電話番号・リスクのチェック

コード	ステータス	意味
`invalid_account_input`	`400`	口座情報が有効ではありません
`country_not_covered`	`404`	このチェックはこの国またはこの種類の口座に対応していません
`bank_not_covered`	`404`	このチェックはこの銀行に対応していません
`bank_verification_not_available`	`404`	Bank Verificationはまだ利用できません
`account_check_unavailable`	`503`	チェックが一時的に利用できません。リクエストは課金されていません
`phone_provider_unavailable`	`502`	電話番号検証が一時的に利用できません。課金は発生せず、試行回数も消費されません
`risk_lookup_unavailable`	`502`	リスク照会が一時的に利用できません。リクエストは課金されていません

法人確認 (KYB)

コード	ステータス	意味
`kyb_registry_provider_unavailable`	`502`	法人登記が一時的に利用できません
`kyb_registry_country_unsupported`	`400`	登記検索はこの国に対応していません
`kyb_registry_search_limit_reached`	`429`	アプリケーションが1時間あたり600件の有料検索の上限に達しました
`kyb_session_not_writable`	`409`	セッションは終了しています
`kyb_step_mismatch`	`409`	セッションは別のステップにあります。`next_step`でそのステップが示されます
`kyb_no_party_drafts`	`409`	送信する関係者の下書きがありません
`kyb_parties_already_submitted`	`409`	関係者はすでに送信されています
`kyb_party_kyc_session_not_deleted`	`409`	関係者の認証がまだ有効なため、再生成できません

Digital IDウォレット

コード	ステータス	意味
`wallet_unavailable`	`403`	このウォレットはお使いのアプリケーションでは利用できません
`wallet_provider_unavailable`	`502`	ウォレットを起動できず、何も作成されていません
`wallet_not_configured`	`503`	この環境からはウォレットに接続できません

レポートとケース

コード	ステータス	意味
`report_deletion_pending`	`409`	レポートは削除中です。削除を再度実行して、ファイルの消去を完了してください
`report_storage_unavailable`	`503`	レポートのファイルを消去できませんでした。削除を再度実行してください
`wallet_address_deletion_incomplete`	`503`	保存されたファイルを削除できなかったため、削除が中断されました。もう一度お試しください
`case_request_not_waiting`	`409`	このリクエストはもう顧客の対応を待っていないため、リマインドする内容がありません
`case_request_reminder_too_soon`	`429`	最近リマインダーが送信されています。`retry_at`で次に送信できる時刻が示されます

電子署名

コード	ステータス	意味
`signature_not_found`	`404`	署名が存在しません
`signature_field_not_found`	`404`	署名フィールドが存在しません
`signature_not_signed`	`404`, `409`	書類が署名されていません

セッション作成時、以下の書類の問題は、問題のあるフィールドの値としてステータス400で返されます。例えば{"sign": "signature_document_changed"}のようになります。

値	意味
`signature_document_changed`	書類が最初に送信されたものと異なります
`signature_document_not_supported`	書類の形式がサポートされていません
`signature_document_conversion_failed`	書類を変換できませんでした
`field_anchor_not_found`	フィールドのテキストアンカーが書類内に見つかりませんでした
`field_value_missing`	フィールドに値がありません

Webhook

コード	ステータス	意味
`webhook_url_missing`	`400`	配信にURLが記録されていないため、何も送信されません
`invalid_webhook_payload`	`400`	Webhookのデータが有効な形式ではありません
`webhook_resend_error`	`400`	保存された配信に再度署名できなかったか、試行を完了できませんでした

再試行と冪等性

失敗の中には、繰り返しても安全なものとそうでないものがあります。

429: Retry-Afterヘッダーで示された時間だけ待ってから再試行してください。
502と503: エンドポイントのリファレンスに課金されていないと記載されている場合は、バックオフを入れて再試行してください。電話番号、メールアドレス、銀行、リスクの各チェックがこれに該当します。
POST /v3/database-validation/での502: まず各validation_errorsエントリを確認してください。このステータスだけでは一時的な障害を意味しないためです。
削除時の503: 200が返るまで同じリクエストを繰り返してください。
その他の4xx: 同じリクエストは同じように失敗するため、まずリクエストを修正してください。

POST /v3/aml/とDigital IDウォレット検証は、最大255文字のIdempotency-Keyヘッダーを受け付けます。同じキーと同じボディでリクエストを繰り返すと保存済みのレスポンスが返されるため、処理と課金は1回しか行われません。同じキーで異なるボディを送ると409が返ります。また、最初のリクエストがまだ実行中の間は、ウォレットのエンドポイントはRetry-After付きの409を返します。 POST /v3/session/には冪等性キーがありません。作成がタイムアウトした場合は、別のセッションを作成する前にvendor_dataでセッションを一覧表示してください。

ガイド

認証

Model Context Protocol (MCP)

Web SDK

ネイティブSDK

サーバーSDK

連携

Didit APIエラー：ステータスコード、レスポンス本文、対処法

ステータスコード

エラーボディ

APIキーのエラー

クレジット不足

エラーコード

アクセスと請求

リクエストと冪等性

銀行・電話番号・リスクのチェック

法人確認 (KYB)

Digital IDウォレット

レポートとケース

電子署名

Webhook

再試行と冪等性

関連情報

​ステータスコード

​エラーボディ

​APIキーのエラー

​クレジット不足

​エラーコード

​アクセスと請求

​リクエストと冪等性

​銀行・電話番号・リスクのチェック

​法人確認 (KYB)

​Digital IDウォレット

​レポートとケース

​電子署名

​Webhook

​再試行と冪等性

​関連情報

ステータスコード

エラーボディ

APIキーのエラー

クレジット不足

エラーコード

アクセスと請求

リクエストと冪等性

銀行・電話番号・リスクのチェック

法人確認 (KYB)

Digital IDウォレット

レポートとケース

電子署名

Webhook

再試行と冪等性

関連情報