維運與疑難排解
限流與使用量
X-RateLimit 標頭、429 的處理，以及降低請求量的做法
所有 API 請求均帶有目前的使用量與限流狀態：
HTTP/1.1 200 OK
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1783296060| 標頭 | 意義 |
|---|---|
X-RateLimit-Limit | 目前窗口允許的請求數 |
X-RateLimit-Remaining | 目前窗口剩餘的請求數 |
X-RateLimit-Reset | 窗口重置的 Unix 時間戳（秒） |
超過上限的回應
回應 429 錯誤，並帶有 Retry-After 標頭與標準錯誤物件：
HTTP/1.1 429 Too Many Requests
Retry-After: 60
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1783296060{
"error": {
"code": "ERR_RATE_LIMIT_EXCEEDED",
"message": "Rate limit exceeded. Retry after 60 seconds",
"details": { "retry_after": 60, "limit": 1000, "window": "minute" },
"request_id": "req_01j9f3k2m1"
}
}請至少等待 Retry-After 秒再重試。
最佳實務
- 使用批次端點建立大量提交。
POST /submissions/batch一次最多 100 筆，將計為一個請求。 - 以 webhook 取代輪詢。 追蹤批閱進度應使用 Webhook 訂閱
submission.completed事件，而非使用輪詢。