エラーハンドリング

QuickTrust API のエラーレスポンスの形式と対処方法について説明します。

エラーレスポンスの形式

すべてのエラーレスポンスは以下の形式で返されます：

{
  "error": "Bad Request",
  "message": "Invalid request body"
}

HTTP ステータスコード

2xx 成功

コード	説明
200	成功
201	リソース作成成功
202	受理（非同期処理開始）
204	成功（レスポンスボディなし）

4xx クライアントエラー

コード	説明	対処方法
400	リクエストが不正	リクエストボディを確認
401	認証エラー	APIキーを確認
403	アクセス権限なし	リソースへの権限を確認
404	リソースが見つからない	IDを確認
409	競合（重複など）	既存リソースを確認
410	リソースが期限切れ	新しいセッションを作成
422	処理できないエンティティ	ビジネスロジックの要件を確認

5xx サーバーエラー

コード	説明	対処方法
500	内部サーバーエラー	サポートに連絡
503	サービス利用不可	時間をおいてリトライ

よくあるエラーと対処方法

400 Bad Request

リクエストボディのバリデーションエラー：

{
  "error": "Bad Request",
  "message": "callbackUrl must be a valid URL"
}

対処方法: リクエストボディの形式を確認してください。

401 Unauthorized

APIキーが無効または未指定：

{
  "error": "Unauthorized",
  "message": "Invalid or missing API key"
}

対処方法:

• Authorization ヘッダーが正しく設定されているか確認
• APIキーが有効か確認（管理画面で確認可能）

404 Not Found

指定したリソースが存在しない：

{
  "error": "Not Found",
  "message": "Verification session not found"
}

対処方法:

• リソースIDが正しいか確認
• リソースが削除されていないか確認

409 Conflict

処理が競合している：

{
  "error": "Conflict",
  "message": "Verification is already processing"
}

対処方法:

• 既存の処理が完了するのを待つ
• 重複したリクエストを送信していないか確認

410 Gone

セッションの有効期限切れ：

{
  "error": "Gone",
  "message": "Verification session has expired"
}

対処方法:

• 新しいセッションを作成してください

422 Unprocessable Entity

ビジネスロジック上の制約違反：

{
  "error": "Unprocessable Entity",
  "message": "Cannot reprocess: verification is not in a reprocessable state"
}

対処方法:

• エラーメッセージを確認し、要件を満たすようにリクエストを修正

503 Service Unavailable

外部サービスが一時的に利用不可：

{
  "error": "Service Unavailable",
  "message": "Liveness service temporarily unavailable"
}

対処方法:

• 時間をおいてリトライしてください
• 継続する場合はサポートに連絡

リトライ戦略

指数バックオフ

5xx エラーの場合は、指数バックオフでリトライすることを推奨します：

async function requestWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status >= 500) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise((resolve) => setTimeout(resolve, delay));
        continue;
      }
      throw error;
    }
  }
  throw new Error('Max retries exceeded');
}

// 使用例
const result = await requestWithRetry(() =>
  createVerificationSession({ callbackUrl: 'https://...' }),
);

リトライすべきエラー

エラー	リトライ	理由
500	はい	一時的なサーバーエラーの可能性
503	はい	サービス復旧を待つ
400	いいえ	リクエストを修正する必要
401	いいえ	認証情報を修正する必要
404	いいえ	リソースが存在しない

デバッグのヒント

ログの記録

エラー発生時は以下の情報を記録することを推奨します：

• HTTP ステータスコード
• エラーメッセージ
• リクエストボディ（機密情報を除く）
• タイムスタンプ