契約にエラースキーマを定義し、Stripe エラーを型付き ORPCError に変換する

背景

packages/api-contract の契約はプロシージャの入出力・エラー仕様を定義する位置づけだが、現状どのプロシージャもエラースキーマを持たない。ハンドラ内で投げる例外(例: 確定した Invoice に支払い URL が無い場合の Error)や Stripe SDK が投げるエラーは、既定の RPCHandler で一律 INTERNAL_SERVER_ERROR にマスクされてクライアントへ返る。

問題

クライアントは「入力が不正(存在しない customer や price を指定した)」と「サーバー側の不具合」を区別できず、いずれも 500 として観測する。とくに invoices.create のような決済エンドポイントでは、呼び出し側で回復可能なユーザー起因のエラーと、真の障害とが同じ見え方になり、適切なエラー表示や再試行の判断ができない。

やること

• 契約(oc の .errors)にエラースキーマを定義する(例: BAD_REQUEST / NOT_FOUND / FORBIDDEN)
• ハンドラで Stripe のエラーを type で分岐し、適切な ORPCError に変換する(例: 不正な引数は 400)。Stripe の内部情報はクライアントへ漏らさない
• ドメイン由来のエラー(支払い URL が得られない等)も、暗黙の 500 ではなく ORPCError として明示的に投げる(ユーザー起因ではない想定外状態のため分類は INTERNAL_SERVER_ERROR のままとし、4xx には振り替えない)

受け入れ条件

• 不正な customer / price を指定した invoices.create が 4xx として返り、Stripe の内部情報を含まないこと
• クライアントが契約からエラーの型を参照できること

関連

無認証の変更系を塞ぐ暫定ガードと、その後の認可導入(#15)で FORBIDDEN の利用が広がる。本 issue はエラー表現の土台を整える。

Start in packages/api-contract and inspect how each procedure is declared, including the oc.errors definitions, then trace invoices.create through its handler and the default RPCHandler behavior. Review the Stripe error types and existing domain errors before choosing mappings. Done means the contract exposes typed errors, invalid customer or price inputs return sanitized 4xx responses, and unexpected domain failures remain explicit INTERNAL_SERVER_ERROR responses.