エラーハンドリング

標準エラーコードでエラーを適切に処理します。

エラーレスポンス形式

すべてのAPIエラーはエラーコードと人間が読めるメッセージを含む一貫したJSON形式に従います。

{
  "error": {
    "code": "error_code_here",
    "message": "A human-readable description of the error."
  }
}

エラーコード

ステータスコード説明
401missing_api_keyリクエストにX-API-Keyヘッダーが含まれていません。
401invalid_api_key提供されたAPIキーが無効、期限切れ、または取り消されています。
402quota_exceeded月間リクエストクォータを超過しました。プランをアップグレードしてください。
422invalid_imageimageフィールドが不足、無効なbase64、または5MBを超えています。
422invalid_requestリクエストボディが有効なJSONではありません。
502inference_errorML推論サービスが一時的に利用できません。バックオフで再試行してください。

エラーレスポンスの例

APIキー不足 (401)

{
  "error": {
    "code": "missing_api_key",
    "message": "No API key provided. Include your key in the X-API-Key header."
  }
}

無効な画像 (422)

{
  "error": {
    "code": "invalid_image",
    "message": "Image exceeds the maximum size of 5 MB."
  }
}

推論エラー (502)

{
  "error": {
    "code": "inference_error",
    "message": "ML inference service is temporarily unavailable. Please retry."
  }
}

ベストプラクティス

  • レスポンスボディを解析する前に、必ずHTTPステータスコードを確認してください。
  • 502エラーには指数バックオフを実装してください（推論サービスがコールドスタート中の可能性があります）。
  • レスポンスヘッダーでクォータ使用量を監視し、予期しない402エラーを避けましょう。
  • 401や422エラーは再試行しないでください。修正が必要なクライアント側の問題です。
  • プログラムによるエラー処理にはメッセージではなくerror.codeフィールドを使用してください。

リトライの例

一時的なエラーに対する指数バックオフのJavaScript例：

async function analyzePalm(imageBase64, apiKey, retries = 3) {
  for (let attempt = 0; attempt < retries; attempt++) {
    const res = await fetch(
      "https://api.trace-line.site/v1/palm/analyze",
      {
        method: "POST",
        headers: {
          "X-API-Key": apiKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ image: imageBase64 }),
      }
    );

    if (res.ok) return res.json();

    const error = await res.json();

    // Only retry on transient errors
    if (res.status !== 502) throw error;

    // Exponential backoff: 1s, 2s, 4s
    await new Promise((r) =>
      setTimeout(r, 1000 * Math.pow(2, attempt))
    );
  }

  throw new Error("Max retries exceeded");
}