錯誤與限流

錯誤回應結構、完整的 HTTP 狀態碼表、限流行為，以及適用於 Atlas Cloud 的重試策略。

錯誤回應結構

Atlas Cloud 會依您呼叫的 API 區塊返回三種不同的錯誤結構。動手寫解析邏輯前，請先確認是哪一種。

用於 LLM 協定端點與媒體生成端點：

{
  "code": 401,
  "msg": "unauthorized",
  "request_id": "…",
  "data": null
}

每個回應都會帶有 X-Request-ID 標頭。請記錄下來——這是技術支援追查某次特定呼叫最快的方式。

HTTP 狀態碼

狀態碼	意義	該怎麼做
`400`	請求格式錯誤：請求主體無法解析、缺少 `model`、Content-Type 不正確、保存期限標頭無效，或 `webhook_url` 不合法	修正請求。`msg` 欄位會指出具體問題
`401`	身份驗證失敗——金鑰遺漏、無效或已過期	檢查金鑰。請注意：URL 路徑寫錯同樣會返回 401，因此也要一併核對端點
`402`	餘額不足，或 Coding Plan 額度已用盡	儲值
`403`	帳戶或使用者沒有權限——包含以 Coding Plan 金鑰呼叫不接受該類金鑰的模型	檢查金鑰的權限範圍，或聯繫技術支援
`404`	找不到資源。就模型而言，這也包含您的帳戶無權使用的模型	對照模型庫核對模型 ID
`413`	請求主體超過 50 MB	改用 URL 而非內嵌 Base64，或先上傳檔案
`429`	觸發限流	退避後重試——請見下文
`451`	您所在地區受到封鎖	不可重試
`500`	內部錯誤	重試一次，若仍失敗請帶上 request ID 回報
`503`	服務暫時無法使用	退避後重試
`504`	同步請求超過最長等待時間	改用非同步流程並輪詢

401 不一定代表您的金鑰有問題。閘道會先驗證身份再進行路由，因此路徑打錯也會產生 401 而不是 404。如果同一把金鑰在別處可用，請先檢查 URL。

任務層級錯誤碼

非同步任務失敗時，data.error_code 會帶上一個平台數字錯誤碼，比 HTTP 狀態碼更精確。例如 1039 代表輸入內容被內容審核拒絕。

data.error 則是可讀的錯誤描述。請把兩者連同 prediction ID 一起記錄下來。

限流

限流會依帳戶與模型分別計算。超出限制會返回 429。

LLM 與媒體端點不會返回 X-RateLimit-Limit、X-RateLimit-Remaining 或 Retry-After。您無法從回應標頭讀取剩餘配額——請在用戶端自行實作退避。

/public/v1 計費端點是例外：它們的 429 回應確實會帶 Retry-After。

若正式環境需要更高的限額，請聯繫我們，並說明預期的請求量與使用的模型組合。

重試策略

對 429、500、503、504 以及網路層錯誤進行重試。不要重試 400、401、402、403、404 或 451——重試結果完全相同。

讀取類請求可以放心重試。但重試生成任務的提交請求要格外小心：逾時的請求其實可能已經被受理，貿然重試會建立（並計費）第二個任務。較穩妥的做法是非同步提交再輪詢，如此一來即使遺失回應，也不會遺失任務。

import time, random, requests

RETRYABLE = {429, 500, 503, 504}

def call_with_retry(url, payload, api_key, max_attempts=4):
    for attempt in range(max_attempts):
        response = requests.post(
            url,
            json=payload,
            headers={"Authorization": f"Bearer {api_key}"},
            timeout=60,
        )
        if response.status_code not in RETRYABLE:
            return response

        if attempt == max_attempts - 1:
            break

        # 指數退避 + 抖動，避免大量用戶端同時重試
        delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
        time.sleep(delay)

    return response

串流錯誤

如果串流請求在串流建立之前就失敗，您會收到一般的 HTTP 錯誤。一旦串流已經開始，連線會保持開啟，錯誤會以事件的形式出現在串流中——因此串流呼叫返回 200 並不保證回應是完整的。請務必處理串流中途中斷的情況。

串流中也可能出現以 : 開頭的 SSE 註解行，作為 keep-alive 訊號。它們不是資料，必須忽略——大多數 SSE 用戶端會自動處理，但自行撰寫的解析器往往不會。

取得協助

回報問題時，請提供：

失敗回應中的 X-Request-ID 標頭
非同步任務的 prediction ID
精確的模型 ID 與時間戳記

歡迎透過技術支援與我們聯繫。

錯誤回應結構

HTTP 狀態碼

任務層級錯誤碼

限流

重試策略

串流錯誤

取得協助

相關內容

LLM API 協定

預測

API 金鑰

On this page