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

Parky BFF（Cloudflare Workers）が返すすべての HTTP エラーコードと、 観測性のために吐く 1 行 JSON ログの仕様をまとめます。 実体は api/src/lib/errors.ts と api/src/lib/logger.ts が SSoT。

The single source of truth for every HTTP error code returned by the Parky BFF (Cloudflare Workers), and for the one-line JSON structured log format used for observability. Code lives in api/src/lib/errors.ts and api/src/lib/logger.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.

{
  "error": {
    "code":       "not_found",                       // ErrorCode（下表参照）
    "message":    "parking_lot not found",           // 人間可読メッセージ
    "request_id": "018f3b7a-4b5c-4c4b-..."           // x-request-id ヘッダと一致
  }
}

クライアントは 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

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).