回應格式

說明成功回應、錯誤回應、meta 欄位與 response header 的統一格式。

所有 API 模組皆採用一致的 response envelope。成功回應以 data 與 meta 回傳結果與請求資訊；錯誤回應以 error 回傳錯誤碼、訊息與追蹤資訊，方便工程串接、除錯、稽核與對帳。

成功信封

{
  "data": <實際資料>,
  "meta": {
    "request_id": "9b1c2d3e-...",
    "pagination": { "limit": 20, "offset": 0, "total": 134 },
    "credit_cost": 5,
    "credit_remaining": 9995
  }
}

• data — 實際的業務資料。可能是物件、陣列，或列表型端點的項目集合。

• meta — 與本次請求有關的中繼資訊。欄位皆為選用，沒有就不會出現：

欄位	何時出現	意義
request_id	一律	本次請求的追蹤碼，同 X-Request-Id
pagination	列表型端點	分頁狀態，見分頁
credit_cost	有計費時	本次扣除的 credit
credit_remaining	有計費時	扣除後的剩餘餘額

客戶端應依「欄位存在才解析」的原則處理 meta。某些欄位只會在特定 endpoint、計費方案或列表型查詢中出現；欄位不存在不代表錯誤。

錯誤信封

錯誤一律回傳對稱的結構，詳見錯誤處理：

{
  "error": {
    "code": "rate_limited",
    "message": "rate limited, retry after 3s"
  }
}

回應 header

Header	說明
X-Request-Id	請求追蹤碼（可自帶沿用）
X-Credit-Cost	本次請求扣除的 credit，僅成功且需計費時出現
X-Credit-Remaining	扣點後剩餘 credit，僅適用於 Credit 方案
Retry-After	遇到 429 rate limit 時，建議等待幾秒後重試

下一步

錯誤處理分頁