エラーハンドリング

API errors は安定した JSON envelope を使用するため、integration は status と code で分岐できます。

Error envelope

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {},
    "requestId": "req_123"
  }
}

code と message は必須です。details と requestId は任意です。programmatic handling には code を使用し、 message は変更される可能性のある human-readable text として扱ってください。

すべての response には X-Request-Id header が含まれます。Error envelopes には同じ値が error.requestId として含まれます。support に問い合わせる際はこの値を含めると、 VoiceAgent が失敗した request を logs と Sentry events に関連付けられます。独自の X-Request-Id header を送信することもできます。その場合、VoiceAgent は同じ値を返します。

Status codes

VoiceAgent は ADR-011 status-code catalog に従います。主なパートナー向け statuses は次のとおりです。

Status	Meaning
`400`	request が不正、解析不能、または必要な transport material が不足しています。
`401`	authentication がない、無効、期限切れ、または拒否されています。
`403`	caller は認証済みですが、その operation を実行する権限がありません。
`404`	指定された resource は caller の workspace scope 内に存在しません。
`422`	request は解析されましたが、domain rule または semantic precondition に失敗しました。
`429`	rate limit または quota により request が拒否されました。
`500`	予期しない server failure が発生しました。
`503`	dependency、configured capability、または一時的な service capacity が利用できません。

Handling pattern

async function voiceagent(path, options = {}) {
  const response = await fetch(`https://api.voiceagent.example/api/v1${path}`, {
    ...options,
    headers: {
      Authorization: `Bearer ${process.env.VOICEAGENT_API_KEY}`,
      "Content-Type": "application/json",
      ...options.headers,
    },
  });

  const body = await response.json().catch(() => ({}));

  if (!response.ok) {
    const error = body.error ?? {
      code: "UNKNOWN_ERROR",
      message: "VoiceAgent request failed",
    };

    if (response.status === 401) {
      throw new Error("Check VOICEAGENT_API_KEY");
    }

    if (response.status === 429) {
      const retryAfter = response.headers.get("Retry-After");
      throw new Error(`Rate limited. Retry after ${retryAfter ?? "a short delay"}`);
    }

    throw new Error(`${response.status} ${error.code}: ${error.message}`);
  }

  return body;
}

Validation details

validation failures には structured details が含まれることがあります。すべての endpoint が同じ details shape を返すとは限らないため、logs と developer diagnostics に使用してください。