エラーカタログ & 構造化ログ Error Catalog & Structured Logging

Parky BFF（Cloudflare Workers）が返すすべての HTTP エラーコードと、 観測性のために吐く 1 行 JSON ログの仕様をまとめます。 実体は api/src/lib/errors.ts（ERROR_CATALOG / ApiError / ショートハンド） と api/src/lib/logger.ts、 正規化と response 整形は api/src/middleware/error-handler.ts。

The single source of truth for every HTTP error code returned by the Parky BFF (Cloudflare Workers) and for the one-line JSON log format. Code lives in api/src/lib/errors.ts (ERROR_CATALOG / ApiError / shortcuts), api/src/lib/logger.ts, and the normalization + response shaping happens in api/src/middleware/error-handler.ts.

1. 応答フォーマット1. Response format

すべてのエラー応答は統一形式。ステータスコードは code から決まる（ルート側で status を指定する必要はない）。

Every error response uses the same shape. Status is derived from code — route handlers never pass status explicitly.

// 実装: middleware/error-handler.ts (B-01 Stripe-tier envelope)
{
  "error": {
    "code":        "not_found",                      // ErrorCode（下表参照）
    "message":     "parking_lot not found",          // 人間可読メッセージ
    "message_key": "errors.not_found",               // i18n key（lib/i18n-keys.ts → ApiError.messageKey で override 可）
    "request_id":  "018f3b7a-4b5c-4c4b-...",         // x-request-id ヘッダと一致
    "param":       null,                             // ZodError なら issues[0].path[0]、それ以外 null
    "doc_url":     null                              // ERROR_CATALOG[code].doc_url（一部 code のみ）
  }
}

message_key / param / doc_url は B-01 (2026-04-28) で追加。 旧クライアントとの互換のため optional + nullable で常時付与。doc_url 形式は https://docs.parky.co.jp/errors/<code>。

message_key / param / doc_url were added in B-01 (2026-04-28). They are always emitted (optional + nullable) for backward compatibility. doc_url follows https://docs.parky.co.jp/errors/<code>.

1.1 throw → response の流れ1.1 throw → response flow

flowchart LR
  R[route handler
throw badRequest / ApiError / HTTPException] --> EH[middleware/
error-handler.ts]
  EH --> N[normalizeToApiError]
  N -->|HTTPException| F[fromHTTPException]
  N -->|Error その他| INT[ApiError 'internal_error' 500]
  F --> AE[ApiError]
  N -->|ApiError| AE
  AE --> RP[buildApiErrorResponse
code / status / message_key / param / doc_url / request_id]
  AE -->|status >= 500| SEN[Sentry capture]
  AE -->|prod| RED[redactErrorForProduction
stack/cause/detail を落とす]
  RED --> LOG[logger warn 4xx / error 5xx]
  RP --> CLIENT[Client]
      

クライアントは code で機械的に分岐し、message は UI に表示しない（i18n 対応のため、 ユーザー向け文言はクライアント側で code に対応するローカライズ文字列を用意する方針）。 request_id はサーバーログと突合するキー。

Clients branch on code programmatically and do not render message as-is (for i18n, map each code to a localized string on the client side). request_id correlates with server logs.

2. エラーコード一覧（ERROR_CATALOG）2. Error codes (ERROR_CATALOG)

2-1. 汎用 HTTP コード2-1. Generic HTTP codes

各 entry は retryable / clientAction（reauthenticate / retry_after / upgrade_plan / contact_support） / doc_url を任意で持つ（M-24 拡張、E-4 doc URL）。SDK はこれを参照して自動再送 / 再認証 / 課金導線を選択する。

Each entry can carry optional retryable / clientAction (reauthenticate / retry_after / upgrade_plan / contact_support) / doc_url (M-24 + E-4). SDKs use these to drive auto-retry, re-auth, or upgrade flows.

2-2. 業務固有コード2-2. Business-specific codes

汎用コードに寄せきれない「UI がコードで分岐したい業務エラー」はカタログに個別追加する。 命名は英語小文字スネークケース、status は最も近い HTTP 区分に合わせる。

Business errors that clients must branch on by code (beyond the generic codes) are added individually. Names are lowercase snake_case and status follows the nearest HTTP category.

3. コード投げ方（コード側の書き方）3. How to throw from code

ルート / ミドルウェア / ライブラリから投げる時は、ショートハンド関数か ApiError 直接インスタンス化の二通り。生の HTTPException は使わない。

Throw either via a shortcut function or by constructing ApiError directly. Never use raw HTTPException.

import {
  badRequest, unauthorized, forbidden,
  notFound, conflict, unprocessable,
  rateLimited, badGateway, serviceUnavailable,
  ApiError,
} from "../lib/errors";

// 1) ショートハンド（推奨）
if (!body.name) throw badRequest("name is required");
if (!token)     throw unauthorized("Missing bearer token");
if (row == null) throw notFound();

// 2) 業務コードは ApiError を直接
if (!creds) throw new ApiError("iap_not_configured");
if (!plan)  throw new ApiError("unknown_product", `productId=${id}`);

// 3) 原因例外は第 2/3 引数の cause に積む（ログの err.cause に出る）
try {
  await upstream();
} catch (err) {
  throw badGateway("LLM call failed", err);
}

4. 構造化ログ（lib/logger.ts）4. Structured logging (lib/logger.ts)

Workers の stdout は Cloudflare Logs / Tail / Logpush にそのまま流れるので、 すべてのログは 1 行 JSONで吐く。console.* の直接呼出しは禁止 （lib/logger.ts 内部のみ許可）。

Workers stdout flows to Cloudflare Logs / Tail / Logpush verbatim, so every log line is one-line JSON. Direct console.* calls are disallowed (allowed only inside lib/logger.ts).

4-1. 出力スキーマ4-1. Output schema

4-2. 出力例4-2. Sample lines

// HTTP アクセスログ（毎リクエスト末尾に 1 行）
{"ts":"2026-04-19T12:34:56.789Z","level":"info","msg":"request completed",
 "scope":"http","request_id":"018f...","method":"GET","path":"/v1/parking-lots",
 "status":200,"latency_ms":42}

// 4xx はアクセスログ前に warn が 1 行
{"ts":"...","level":"warn","msg":"request failed","scope":"http",
 "request_id":"018f...","method":"POST","path":"/v1/me/vehicles",
 "status":422,"error_code":"unprocessable_entity",
 "err":{"name":"ApiError","message":"Validation failed","code":"unprocessable_entity","status":422}}

// Cron
{"ts":"...","level":"info","msg":"done","scope":"cron.sponsor-proximity",
 "sponsors_evaluated":12,"users_matched":48,"notifications_sent":45,"failed":3,
 "elapsed_ms":1523}

// Queue consumer
{"ts":"...","level":"info","msg":"run finished","scope":"queue.store-sync",
 "sync_run_id":"018f...","store":"app_store","task":"reviews",
 "status":"success","rows_upserted":37}

4-3. ログの書き方4-3. How to log

// 1) HTTP ルート（c.var.log が request_id 付き logger）
app.get("/v1/foo", (c) => {
  c.var.log.info("foo fetched", { foo_id });
  c.var.log.warn("fallback triggered", { reason });
  c.var.log.error("db query failed", err, { query_id });
});

// 2) cron / queue / library
import { createLogger } from "../lib/logger";

const log = createLogger(env, { scope: "cron.my-job", run_id });
log.info("started");
log.error("task failed", err);

// 3) child logger で context を追加
const childLog = log.child({ sync_run_id });
childLog.info("sub-task done");

5. 分析クエリ例5. Analysis queries

Cloudflare Tail / Logs Engine / Logpush 先（S3/Loki 等）で jq を叩く想定。

Assuming jq against Cloudflare Tail / Logs Engine / Logpush sinks (S3, Loki, etc).

# 5xx のみ抽出
jq 'select(.level=="error")'

# 特定 request_id でトレース（HTTP → LLM → DB）
jq 'select(.request_id=="018f3b7a-...")'

# Queue 系だけを時系列で
jq 'select(.scope | startswith("queue."))'

# 特定の業務コードを集計
jq 'select(.err.code=="iap_not_configured")' | jq -s 'length'

# p95 レイテンシ（アクセスログ）
jq -r 'select(.msg=="request completed") | .latency_ms' \
  | sort -n | awk 'NR==int(NR*0.95){print}'

# scope 別のエラー件数
jq -r 'select(.level=="error") | .scope' | sort | uniq -c | sort -rn

6. 新しいコードを追加する手順6. Adding a new code

1. api/src/lib/errors.ts の ERROR_CATALOG に { status, message } を追加する。命名は英語小文字スネークケース。
2. Add { status, message } to ERROR_CATALOG in api/src/lib/errors.ts. Name in lowercase snake_case.
3. 頻繁に使うならショートハンド関数（badRequest 等と同じパターン）を追加する。
4. Add a shortcut function if it'll be used frequently (follow the badRequest pattern).
5. 呼出側で throw new ApiError("new_code", "...") or ショートハンドを使う。
6. Throw via throw new ApiError("new_code", "...") or the shortcut.
7. このドキュメント（docs/api-errors.html）の該当テーブルに行を追加する。
8. Append a row to the table in this document (docs/api-errors.html).
9. クライアント側（モバイル / admin / public web）でハンドリング方針を決めて実装する。
10. Decide and implement the client-side handling (mobile / admin / public web).