エラーコード
このページはエラー処理の唯一の情報源です。SDK 固有のエラーコードは各 SDK のエラー処理ページに記載されています。このページでは API コントラクトレベルのエラーを扱います。
HTTP ステータスコード
| コード | 意味 | 適用範囲 |
|---|---|---|
200 OK | リクエストが成功しました。 | すべてのコントラクト。 |
201 Created | リソースが作成されました（まれ。ほとんどの作成は 200 を返します）。 | API コントラクト。 |
400 Bad Request | ペイロードが不正な形式であるか、必須フィールドが欠落しています。本文に問題のあるフィールドが記載されます。 | すべてのコントラクト。 |
401 Unauthorized | 認証が欠落、期限切れ、または無効です。 | すべてのコントラクト。 |
403 Forbidden | 認証は有効ですが、テナントはリクエストされたリソースに対して有効になっていません（例：APIKEY にない機能を呼び出す）。 | Web & SDK、API。 |
404 Not Found | リソースが存在しないか、認証済みテナントに属していません。 | すべてのコントラクト。 |
409 Conflict | リソースは存在しますが、この操作に適した状態にありません（例：まだ進行中のプロセスからドキュメントを取得する）。 | Web & SDK、API。 |
410 Gone | リソースは存在しましたが、保持ポリシーに従って削除されました（ドキュメント取得エンドポイント）、またはプロセスは存在しますがエラー状態で終了しました — プロセスの取得を参照。 | ドキュメント取得エンドポイント、API Get Process。 |
429 Too Many Requests | レート制限に達しました。指数バックオフで再試行してください。 | すべてのコントラクト。 |
5xx | プラットフォームエラー。バックオフで再試行してください。継続する場合は、レスポンスボディとタイムスタンプを添えてサポートに連絡してください。 | すべてのコントラクト。 |
認証エラー（401）
| 原因 | 症状 |
|---|---|
| 間違った秘密鍵（誤ったキーで署名されたアサーション） | 401、Authentication failed (1.2.21) |
aud が環境 URL と一致しない | 401 |
exp クレームが過去の時刻 | 401、Authentication failed |
サポートされていないアルゴリズム（RS256 を使用してください） | 401 |
| サンドボックス / 本番の認証情報が混在している | 401（認証情報が正しく見えても） |
APIKEY ヘッダーが欠落している（API コントラクトのみ） | 401 |
x-api-key が無効（Magic Link のみ） | 401 |
完全なトラブルシューティングチェックリストは認証 > 一般的なエラーを参照してください。
機能レベルの結果（200 で否定的な結果）
200 OK はユーザーが検証に合格したことを意味しないことに注意してください — プラットフォームが作業を完了したことを意味します。ユーザー向けの判定は HTTP ステータスではなく、レスポンスボディにあります：
| フィールド | 否定的な値 | 表示される場所 |
|---|---|---|
process.result | PROCESS_RESULT_FAILED | Web & SDK |
process.authenticationInfo.livenessResult | NO | Web & SDK |
liveness | 2 | API |
unicoId.result | no | API |
data.response.unico.result | NOT_APPROVED | Magic Link |
再試行ポリシー
| ステータス | 再試行すべきか | 方法 |
|---|---|---|
5xx | はい | 指数バックオフ（1 秒、2 秒、4 秒、8 秒…）。最大 5 回まで。 |
429 | はい | Retry-After ヘッダーがあれば従う。なければ指数バックオフ。 |
4xx（その他） | いいえ | リクエストが間違っています。再試行前に入力を修正してください。 |
401 | 条件付き | アクセストークンを一度更新してください。新しいリクエストも 401 を返す場合は構造的な問題です — 再試行しないでください。 |
冪等性
IDCloud プラットフォームは現在、作成エンドポイントに冪等性キーのメカニズムを公開していません。POST /client/v1/process または POST /processes/v1 を再試行する際は注意が必要です — 5xx でのネットワークエラーが実際にはサーバーサイドで成功している可能性があり、再試行すると重複プロセスが作成される場合があります。不明な場合は、再試行前に内部の相関 ID で最近のプロセスを取得してください。
SDK エ ラーの所在
Web SDK、Android SDK、iOS SDK、および Flutter SDK のエラーカタログは、各 SDK 専用のエラー処理ページに記載されています：
これらはデバイス側のエラー（カメラ許可拒否、キャプチャタイムアウト、デバイスのネットワーク到達不能）を扱っており、ここに記載されている API 側のエラーとは別です。