エラー

すべてのエラーレスポンスは同じ形です。

{
  "ok": false,
  "error": {
    "code": "E_UNKNOWN_MATERIAL",
    "message": "Material 'allpvs' not found in manifest.",
    "at": "materials[0].name"
  }
}

• code — 安定した機械可読エラーコード。クライアントは message ではなく code で分岐すること。
• message — 人間が読める説明。文言はリリース間で変わる可能性あり。
• at — リクエストボディ内の該当値への JSON-pointer 風パス。フィールド固有のエラーのときだけ存在。

正式なエラーコード

認証 / 認可

HTTP	コード	発生条件
401	E_UNAUTHORIZED	Authorization ヘッダが無いか無効
403	E_FORBIDDEN	認証は成功したが、このユーザーはこの tracking_id にアクセスできない

リクエスト構造

HTTP	コード	発生条件
400	E_INVALID_JSON	ボディが JSON としてパースできない
400	E_MISSING_FIELD	必須トップレベルフィールドが無い
400	E_UNKNOWN_FIELD	認識できないトップレベルキーがある
400	E_TIME_REQUIRED	time.start / time.end / time.tz のどれかが無い
400	E_INVALID_TZ	time.tz が有効な IANA タイムゾーンでない
400	E_INVALID_TIME_RANGE	time.end <= time.start、または範囲がありえない値

Materials / Views / Result

HTTP	コード	発生条件
400	E_UNKNOWN_MATERIAL	仕様書に存在しないマテリアル名
400	E_UNKNOWN_VIEW	result.use が make で定義されていないビューを参照
400	E_UNKNOWN_COLUMN	keep / filter / sort がマテリアルに存在しないカラムを参照
400	E_DUPLICATE_VIEW	make 内で同名ビューが複数
400	E_LIMIT_REQUIRED	count_only でないのに result.limit が無い

機能

HTTP	コード	発生条件
400	E_FEATURE_DISABLED	このサーバーで enabled: false の機能を使っている
400	E_FEATURE_NOT_AVAILABLE	機能は存在するが、サーバーの api_update が機能の since より古い

実行

HTTP	コード	発生条件
400	E_BAD_JOIN	宣言されていない JOIN キーで JOIN しようとした
400	E_CARDINALITY_GUARD	JOIN で行数が安全閾値を超えそう (例: フィルタなしの gsc ↔ allpv)
500	E_EXECUTOR_FAILED	内部実行エラー。ジッター付きで1回だけリトライ可
504	E_TIMEOUT	クエリがサーバーの時間予算を超えた。time を狭める、フィルタを足す、または高価な JOIN を落とす

リトライ戦略

• 401/403 — リトライしない。認証情報を直す。
• 400 (構造系) — 盲目的にリトライしない。クライアント側のバグ。AI クライアントが 400 を受けたら、スキーマが動いている可能性があるので /guide を読み直してクエリを再考する。
• 500 — ジッター付きで1回リトライ。
• 504 — 同じクエリをリトライしない。リクエストを狭める。

次に読むページ

• /query リファレンス — エラーコードが指すリクエストの形。
• サンプル — デバッグ時の基準にできる動くリクエスト。