stable · guide · 0.1.0

Handle quota and limit responses

Hard-limit response

受 Project Credential 保護且有 usage metering 的 API，超過 hard limit 時回傳 429 Too Many Requests、Retry-After header 與穩定錯誤：

{
  "error": {
    "code": "platform_quota_exceeded",
    "message": "The platform resource hard limit has been reached.",
    "retryable": true,
    "details": {
      "resource": "api_traffic",
      "used": 1000,
      "limit": 1000,
      "retry_after_seconds": 312
    },
    "correlation_id": "20000000-0000-4000-8000-000000000016"
  }
}

Retry-After 與 error.details.retry_after_seconds 都表示目前 quota window 的剩餘秒數。保留 correlation_id 供支援調查，不要把被拒絕的工作視為已接受。

Retry safely

只有 error.code 為 platform_quota_exceeded 且 retryable 為 true 時，才依較大的 retry delay 加入 jitter 後重試。具 Idempotency-Key 的 write 必須重用原 key 與相同 body；scheduled invocation 會進入 quota_paused，到 quota window 可用後再恢復，已完成工作不會重跑。

Endpoint throttle 也可能回傳 429，但不保證使用 quota error envelope。先辨識 error code，再套用對應策略；不要以高頻 polling 猜測當前 usage。

可在 projectClient API reference 查看 canonical 429 response contract。