錯誤處理

Poshen API 在錯誤情境統一回傳 JSON 格式，HTTP 狀態碼依據錯誤性質區分。所有錯誤都不會包在 data wrapper 裡。

錯誤回應格式

一般錯誤

{
  "message": "用戶不存在"
}

驗證錯誤（422）

{
  "message": "The given data was invalid.",
  "errors": {
    "id_token": ["The id_token field is required."],
    "game_id": ["The game_id must exist in games."]
  }
}

HTTP 狀態碼

狀態碼	含義	何時出現
200	OK	正常回應
201	Created	資源建立成功
204	No Content	刪除成功，無 body
400	Bad Request	業務邏輯錯誤（如 GameException）
401	Unauthorized	OAuth Token 無效
404	Not Found	資源不存在
409	Conflict	衝突狀態（兌換碼已使用、群組名稱重複等）
422	Unprocessable Entity	驗證失敗
500	Internal Server Error	伺服器端錯誤

例外類別對照

例外	HTTP 狀態	訊息
`InvalidGoogleTokenException`	401	Invalid Google token
`InvalidAppleTokenException`	401	Invalid Apple token
`InvalidJwtException`	401	Invalid JWT token
`UserNotFoundException`	404	User Not Found
`UserException::userNotFound()`	404	用戶不存在
`GameNotFoundException`	404	遊戲不存在
`GameException::NotFound()`	404	遊戲不存在
`RedemptionException::invalidCode()`	404	兌換碼輸入錯誤或已失效
`GroupNameAlreadyExistsException`	409	群組名稱已存在
`RedemptionException::maxUsesExceeded()`	409	兌換碼已經兌換完囉！
`RedemptionException::alreadyRedeemed()`	409	您已使用過此兌換碼
`RedemptionException::expired()`	409	兌換碼過期
`RewardInUseException`	409	Reward is in use and cannot be deleted
`UserException::userFailed()`	400	用戶操作失敗
`InvalidEnvironmentException`	500	Invalid environment configuration

客戶端建議處理

401 → 提示「登入失效」並重新引導 OAuth 流程
404 → 視 endpoint 性質決定，多數情況顯示「資源不存在」
409 → 顯示後端訊息給玩家（已是中文）
422 → 通常是程式 bug，記錄到 Sentry 並顯示通用錯誤訊息
500 → 顯示「伺服器忙碌中」並建議稍後再試