エラー

エラーレスポンスの形、ステータスコード、そのハンドリング方法です。

リクエストが失敗すると、API は何が起きたかを示す error 項目を持つ JSON を返します。これを最初から統合に組み込んでおくと、失敗のログ記録と対応が容易になります。

エラーの形

ほとんどのエラーは次の形です。

{ "error": "Project not found." }

バリデーションエラーは固定の error 値に加えて、各問題を表す details 配列を持ちます。項目単位のフィードバックを表示できます。

{
	"error": "ValidationError",
	"details": [{ "path": ["dueDate"], "message": "Invalid date" }]
}

ステータス	意味	対応
400	不正な入力、ルートパラメータ、クエリパラメータ	リクエストを修正。失敗項目は `details` を確認
401	Bearer トークンがない、または無効	再認証するかアクセストークンを更新
402	クレジットが必要な操作に対してクレジットが不足	クレジットを追加して再試行(クレジット)
403	認証済みだが選択スコープ/ワークスペースで許可されていない	ワークスペースコンテキストと呼び出し元の権限を確認
404	レコードまたは参照が見つからない	ID、エイリアス、参照を確認
409	不正な状態遷移や重複制約などの競合	状態を整えてから再試行
429	レート制限(特に OTP 作成)	バックオフして後で再試行
500	予期しないサーバーエラー	バックオフして再試行。続く場合は報告
502	上流サービスの失敗または不正なレスポンス	バックオフして再試行

再試行は 429 と一時的な 5xx に限定し、必ず指数バックオフを使ってください。400、401、403、404、409 などの 4xx は、リクエストを変えずに再試行しても同じ結果になるため、再試行しないでください。