參考
主要內容錯誤碼
每個業務碼的意思、該怎麼處理,以及哪些錯誤值得重試。
呼叫出錯時,回應會給你一個說明問題類型的數字(code),以及一句給人看的說明(msg)。程式依數字分支,說明拿來顯示或寫進記錄。
回應外層
{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }code是業務碼。200代表成功,其他值都列在下方。- 失敗時沒有
data欄位,只有少數素材庫錯誤會多一個data.reason。 - HTTP 狀態碼也會正確設定(
40201對應 HTTP402)。兩者擇一判斷,不要混用——建議使用更具體的code。 request_id也會出現在X-Request-Id回應標頭。聯絡客服時請附上。
如果回應根本不是 JSON(例如中間網路回傳的 HTML 或純文字頁面),就依 HTTP 狀態碼處理,並把回應內容的開頭寫進記錄。
錯誤說明的語言
msg 與失敗任務的 errorMessage 預設為英文。請求時帶上 Accept-Language(en、ja、ko、de、fr、es、pt-BR、ru、it、pl 其中之一),或在控制台設定 API 錯誤語言,就會改用該語言;其他語言(包括中文)會退回英文。錯誤回應會附上 Content-Language 標頭。錯誤碼不會隨語言改變——這也是永遠不要解析 msg 的原因之一。
當模型提供了具體的失敗原因(例如參考圖片無法讀取),errorMessage 會以英文原文轉達,內部細節已移除。
一般錯誤碼
code | HTTP | 意思 | 要重試嗎? |
|---|---|---|---|
200 | 200 / 202 | 成功 | — |
400 | 400 | 請求或 input 不合法;msg 會指出問題 | 不要,先修正 |
40003 | 400 | 上傳的檔案與上傳票證不符(大小、類型或內容) | 不要,重新申請票證再上傳 |
40004 | 400 | 請求本身合法,但模型目前無法支援這組參數組合 | 不要,修改 msg 指出的參數 |
401 | 401 | 缺少金鑰、金鑰無法辨識或已撤銷(詳情) | 不要 |
403 | 403 | 沒有權限(見權限) | 不要 |
404 | 404 | 不存在,或屬於另一把金鑰 | 不要 |
409 | 409 | 與目前狀態衝突(何時重試) | 視情況 |
40901 | 409 | 報價過期或價格已變動 | 重新報價 |
413 | 413 | 請求內容太大 | 不要,改用上傳,別內嵌 |
429 | 429 | 請求太多 | 要,等 Retry-After 之後 |
500 | 500 | 我們這邊出了問題 | 要,退避後重試 |
503 | 503 | 某個支援服務暫時無法使用 | 要,等 Retry-After 之後 |
餘額與上限
code | HTTP | 意思 | 怎麼處理 |
|---|---|---|---|
40201 | 402 | 點數不足以保留這個任務的金額 | 購買點數後再送出 |
40202 | 402 | 達到金鑰的消費上限 | 在 API 控制台調高上限,或等它重設 |
權限
code | HTTP | 意思 | 怎麼處理 |
|---|---|---|---|
40301 | 403 | 這把金鑰不能呼叫這個模型 | 把模型加入金鑰的允許清單 |
40302 | 403 | 請求來源不在金鑰的 IP 允許清單內 | 加入這個位址,或移除這項限制 |
40303 | 403 | 所在地區不提供服務 | 無法繞過 |
40310 | 403 | 帳戶的電子郵件尚未驗證 | 開啟註冊信中的連結;驗證後金鑰立即可用 |
如果金鑰有效卻收到一般的 403,表示帳戶暫時無法使用 API,請附上 request_id 聯絡客服。
模型可用性
code | HTTP | 意思 | 要重試嗎? |
|---|---|---|---|
50301 | 503 | 這個模型目前無法接受任務 | 要,稍後再試,或換一個模型 |
40004 | 400 | 模型正常,但不支援這組設定 | 不要,修改設定 |
這兩種情況都不會建立任務,也不會保留點數。
任務失敗碼
任務受理後才失敗時,state 為 "failed",errorCode 是下列之一。這份清單是封閉的:遇到其他值,一律當成 upstream_failed 處理。
errorCode | 意思 | 要重試嗎? |
|---|---|---|
invalid_request | 模型不接受這些參數 | 不要,先修正 |
unsupported_combination | 目前不支援這組參數組合 | 不要,換個設定 |
content_rejected | 模型拒絕了這段內容 | 不要,修改提示詞或參考素材 |
invalid_asset | 參考檔案無法讀取或已失效 | 重新上傳後建立新任務 |
rate_limited | 生成服務忙碌 | 要,退避後重試 |
upstream_unavailable | 生成服務暫時無法使用 | 要,稍後重試 |
generation_failed | 執行完畢但沒有產出 | 看情況,同樣的輸入常會同樣失敗 |
timeout | 任務逾時 | 看情況,試試更短或解析度更低的輸出 |
upstream_failed | 其他情況 | 要,退避後重試 |
失敗的任務會釋放保留的點數,不需付費(少數模型對內容拒絕也收費,會在模型頁註明)。errorMessage 以文字說明原因;程式只依 errorCode 判斷。
什麼時候 409 值得重試
| 情況 | 要重試嗎? |
|---|---|
帶同一個 Idempotency-Key 的兩個請求同時抵達 | 要,稍候用同一個鍵重送 |
這個 Idempotency-Key 已用於其他請求或其他金鑰 | 不要 |
| 上傳的檔案或產出仍在處理中 | 要,幾秒後再試 |
對尚未結束的任務呼叫 jobs/retry | 要,等它進入終止狀態後再試 |
對已成功的任務呼叫 jobs/retry | 不要,直接建立新任務 |
| 上傳票證或上傳的檔案已過期 | 不要,重新上傳 |
重試的寫法
只重試第二次有機會成功的錯誤;有 Retry-After 就依它等待,沒有就指數退避:
const RETRYABLE = new Set([429, 500, 503, 50301]);
async function call(path, init, attempts = 4) {
for (let i = 0; i < attempts; i++) {
const res = await fetch(`https://api.popnow.ai/api/v1${path}`, init);
if (!res.headers.get('content-type')?.includes('json')) {
throw new Error(`HTTP ${res.status}: ${(await res.text()).slice(0, 200)}`);
}
const body = await res.json();
if (body.code === 200) return body.data;
if (!RETRYABLE.has(body.code)) throw new Error(`${body.code} ${body.msg} (${body.request_id})`);
const wait = Number(res.headers.get('retry-after')) * 1000 || 2 ** i * 1000 + Math.random() * 500;
await new Promise((r) => setTimeout(r, wait));
}
throw new Error('out of retries');
}import random, time, requests
RETRYABLE = {429, 500, 503, 50301}
def call(method, path, attempts=4, **kwargs):
for i in range(attempts):
res = requests.request(method, f"https://api.popnow.ai/api/v1{path}", timeout=60, **kwargs)
try:
body = res.json()
except ValueError:
raise RuntimeError(f"HTTP {res.status_code}: {res.text[:200]}")
if body["code"] == 200:
return body["data"]
if body["code"] not in RETRYABLE:
raise RuntimeError(f'{body["code"]} {body["msg"]} ({body.get("request_id")})')
retry_after = res.headers.get("retry-after")
time.sleep(float(retry_after) if retry_after else 2**i + random.random() / 2)
raise RuntimeError("out of retries")重試 createTask 時,務必帶同一個 Idempotency-Key,以免一個其實已成功的請求被執行並扣點兩次。
排查問題
- 記下
request_id與code。 - 在 API 控制台的記錄中,用任務 ID 或
request_id找到這個任務。 - 還是解決不了?請聯絡客服,附上
request_id、時間(UTC)與code。永遠不要傳送你的 API 金鑰。

