エラー

エラーの本文は JSON で、_tag にエラーの種類が入ります。HTTP ステータスと _tag で分岐してください。message などの文言は変わることがあるので、分岐に使わないでください。

{ "_tag": "Unauthorized", "message": "..." }

一覧

status	`_tag`	起きる API	意味と対処
400	`CallbackUrlNotAllowed`	作成	`callbackUrl` が許可リストに無い、またはクエリ(`?`)・フラグメント(`#`)が付いている。管理画面の許可リストを確かめる
400	`TenantSettingsUnusable`	作成	テナントの設定が使えない状態。`reason` が `settings_missing`(設定が無い)か `no_steps_enabled`(確認の手順が 1 つも有効でない)。管理画面の設定を確かめるか、担当者に連絡する
400	(上記以外)	作成	本文の形式が合わない(項目の型・長さ・`state` や `metadata` の大きさなど)。送る内容を直す
413	—	すべて	本文が大きすぎる
401	`Unauthorized`	すべて	API キーが無い・間違っている・無効になっている。理由は区別して返さない。キーを確かめ、必要なら管理画面で発行し直す
403	`IpNotAllowed`	すべて	送信元の IP アドレスが許可リストに無い。送信元のアドレスを確かめる
404	`SessionNotFound`	取得・再処理	セッションが無い。別のテナントのもの・ID の形式違いも同じ 404
409	`ReprocessNotAllowed`	再処理	今の状態では再処理できない。再処理を参照
429	`RateLimited`	作成	セッション作成の頻度が上限に当たった。時間をおいて再試行する

Retry-After ヘッダは付きません。429 や 5xx を再試行するときは、間隔を少しずつ広げてください
セッション作成は冪等ではありません。応答を受け取れずに再試行すると、別のセッションができることがあります。使われなかったセッションは期限が来ると expired になり、verification.expired の通知が届きます
知らない _tag や知らないステータスが来ても例外で止まらないようにしてください

// エラー応答の読み方(Node 20 以降)。本文は { "_tag": "...", ... } の JSON で、status と _tag で分岐する。

/** 呼び出し側が取るべき行動 */
export type ErrorAction =
  | "fix_request" // 送った内容か設定を直す。そのまま再試行しても通らない
  | "check_credentials" // API キー・送信元 IP を確かめる
  | "not_found" // 対象が無い(別テナントのもの・ID の形式違いも同じ扱い)
  | "check_state" // 今の状態では受け付けられない。GET で状態を確かめる
  | "retry_later"; // 時間をおいて再試行する

export async function classifyError(response: Response): Promise<{
  action: ErrorAction;
  tag: string | null;
}> {
  const body = (await response.json().catch(() => null)) as { _tag?: unknown } | null;
  const tag = typeof body?._tag === "string" ? body._tag : null;

  switch (response.status) {
    case 400: // CallbackUrlNotAllowed / TenantSettingsUnusable / 入力の形式違い
    case 413: // 本文が大きすぎる
      return { action: "fix_request", tag };
    case 401: // Unauthorized
    case 403: // IpNotAllowed
      return { action: "check_credentials", tag };
    case 404: // SessionNotFound
      return { action: "not_found", tag };
    case 409: // ReprocessNotAllowed
      return { action: "check_state", tag };
    case 429: // RateLimited
      return { action: "retry_later", tag };
    default:
      // 5xx など。知らない _tag・知らない status でも例外にせず、再試行の対象にする。
      // ただしセッション作成は冪等ではない — 再試行すると別のセッションができることがある
      return { action: "retry_later", tag };
  }
}