定期 polling される状態確認 API では、「現在処理中のものが無い」「未発生」「空である」といった空状態を HTTP エラーとして返さず、成功応答の空値として表現する。

判断基準

空状態が通常の利用フローで頻繁に起きるなら、2xx response の nullable body や空配列で返す。存在しないこと自体が異常で、呼び出し側が間違ったリソースを指定している場合だけ 404 などのエラーにする。

なぜ

正常な空状態を 4xx にすると、UI が読み替えできても、API error log、ALB / gateway の 4xx メトリクス、監視アラートにはエラーとして記録され続ける。polling endpoint ではそのノイズが利用者数に比例して増え、実際の異常検知を汚す。

実装上の注意

クライアントだけで 404 を fallback するのは根本対策ではない。API schema、backend response、client 型、mock / test fixture を同じ契約に揃える。空状態を object の中の null フィールド群で表すか body 自体を null にするかは、実体が存在するかどうかで選ぶ。実体が無いなら body 自体を nullable にした方が単純になる。