エラー

エラーは共通のエンベロープを使います（概要を参照）。code で分岐し、meta.request_id をログに記録し、message は人が読むための英語のテキストとして扱ってください。

クライアントエラー

コード	ステータス	意味と対処方法
validation_failed	400	フィールドの検証に失敗しました。field がそのフィールドを示し、details が説明します。フィールドを修正してください。
bad_request	400	リクエストをまったく読み取れませんでした: 不正な JSON、壊れた Content-Encoding ストリーム、中断された本文。修正すべきフィールドはないため、通信経路を確認してください。
validation_error	400	X-Account-Id を禁止しているエンドポイント（/auth/login、/auth/refresh、/auth/swap-company、/auth/logout）に送信しました。
cursor_expired	400	ページネーションのカーソルが24時間より古くなっています。一覧の取得を最初からやり直してください。
unauthenticated	401	トークンがないか無効です。セッションをリフレッシュするか、キーを確認してください。
invalid_signature	401	Webhook の署名を検証できませんでした。Webhook を参照してください。
forbidden	403	トークンは有効ですが、権限がありません。
account_context_mismatch	403	X-Account-Id がトークンのアカウントと一致しません。クライアントが認識している現在の会社がずれています。セッションから読み直してください。
not_found	404	リソースが存在しないか、別のアカウントまたはサイトに属しています。API はこの2つを区別しません。
conflict	409	状態の競合: 楽観的ロック、一意制約、または現在の状態では許可されない操作（例: 統合済みの会話への書き込み）。
idempotency_key_conflict	409	Idempotency-Key が異なる本文で再利用されました。
payload_too_large	413	本文がこのエンドポイントファミリーの上限を超えています。
unsupported_media_type	415	Content-Type が正しくありません。
unprocessable	422	JSON としては有効ですが、ビジネスルールで拒否されました（例: 勤務時間外の予約枠）。
storage_quota_exceeded	422	アカウントがプランのストレージ上限に達しました。details には used_bytes、quota_bytes、requested_bytes が含まれます。空き容量を確保するか、アップグレードしてください。
rate_limited	429	リクエストの頻度を下げてください。Retry-After と details.retry_after_seconds に従ってください。

サーバーエラー

コード	ステータス	意味と対処方法
internal_error	500	予期しない障害です。1回再試行し、それでも失敗する場合は request_id を添えてサポートに連絡してください。
upstream_unavailable	502	ゲートウェイがサービスにまったく到達できませんでした。少し待って再試行すると、たいていは成功します。
service_unavailable	503	計画メンテナンス中か、サーキットブレーカーが作動しています。Retry-After ヘッダーの時間が経過してから再試行してください。
ai_vendor_out_of_funds	503	AI プロバイダーが請求上の理由で呼び出しを拒否しました（ベンダーからの 402 またはクォータの 429）。ベンダーのアカウントに入金してください。再試行しても解決しません。
upstream_timeout	504	サービスが時間内に応答しませんでした。retry_after がある場合は再試行してください。

再試行

429、502、503、504 とネットワーク障害は指数バックオフで再試行し、再試行の際には同じ Idempotency-Key を送って、書き込みが二重に適用されないようにしてください。429 以外の 4xx は再試行しないでください。