PopNowAPI 文件
參考
主要內容

錯誤碼

每個業務碼的意思、該怎麼處理,以及哪些錯誤值得重試。

呼叫出錯時,回應會給你一個說明問題類型的數字(code),以及一句給人看的說明(msg)。程式依數字分支,說明拿來顯示或寫進記錄。

回應外層

{ "code": 40201, "msg": "Insufficient balance", "request_id": "req_…" }
  • code 是業務碼。200 代表成功,其他值都列在下方。
  • 失敗時沒有 data 欄位,只有少數素材庫錯誤會多一個 data.reason。
  • HTTP 狀態碼也會正確設定(40201 對應 HTTP 402)。兩者擇一判斷,不要混用——建議使用更具體的 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 會以英文原文轉達,內部細節已移除。

一般錯誤碼

codeHTTP意思要重試嗎?
200200 / 202成功—
400400請求或 input 不合法;msg 會指出問題不要,先修正
40003400上傳的檔案與上傳票證不符(大小、類型或內容)不要,重新申請票證再上傳
40004400請求本身合法,但模型目前無法支援這組參數組合不要,修改 msg 指出的參數
401401缺少金鑰、金鑰無法辨識或已撤銷(詳情)不要
403403沒有權限(見權限)不要
404404不存在,或屬於另一把金鑰不要
409409與目前狀態衝突(何時重試)視情況
40901409報價過期或價格已變動重新報價
413413請求內容太大不要,改用上傳,別內嵌
429429請求太多要,等 Retry-After 之後
500500我們這邊出了問題要,退避後重試
503503某個支援服務暫時無法使用要,等 Retry-After 之後

餘額與上限

codeHTTP意思怎麼處理
40201402點數不足以保留這個任務的金額購買點數後再送出
40202402達到金鑰的消費上限在 API 控制台調高上限,或等它重設

權限

codeHTTP意思怎麼處理
40301403這把金鑰不能呼叫這個模型把模型加入金鑰的允許清單
40302403請求來源不在金鑰的 IP 允許清單內加入這個位址,或移除這項限制
40303403所在地區不提供服務無法繞過
40310403帳戶的電子郵件尚未驗證開啟註冊信中的連結;驗證後金鑰立即可用

如果金鑰有效卻收到一般的 403,表示帳戶暫時無法使用 API,請附上 request_id 聯絡客服。

模型可用性

codeHTTP意思要重試嗎?
50301503這個模型目前無法接受任務要,稍後再試,或換一個模型
40004400模型正常,但不支援這組設定不要,修改設定

這兩種情況都不會建立任務,也不會保留點數。

任務失敗碼

任務受理後才失敗時,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 就依它等待,沒有就指數退避:

JavaScript
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');
}
Python
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,以免一個其實已成功的請求被執行並扣點兩次。

排查問題

  1. 記下 request_id 與 code。
  2. 在 API 控制台的記錄中,用任務 ID 或 request_id 找到這個任務。
  3. 還是解決不了?請聯絡客服,附上 request_id、時間(UTC)與 code。永遠不要傳送你的 API 金鑰。

本頁內容