错误码

Get3W 有两个层级的错误上报：

• HTTP 错误 —— 请求本身失败时（鉴权、参数校验、余额不足等），以 HTTP 状态码加 JSON 响应体的形式返回
• 任务错误 —— 任务已被接受但在执行过程中失败时，通过任务结果对象返回

HTTP 错误响应格式

/v1/ 接口的 HTTP 错误会返回 code 和 error：

{
  "code": 401,
  "error": "Invalid or revoked API key"
}

字段	类型	说明
code	int	HTTP 状态码（与响应状态一致）
error	string | object	错误描述，或一个嵌套的错误对象

警告

error 通常是字符串，但在部分错误下 —— slug 中的 provider 无法识别、余额不足 —— 它是一个嵌套对象，带有自己的 code 和 error。外层 code 始终是 HTTP 状态码，内层 code 才是业务错误码：

{
  "code": 400,
  "error": {
    "code": 1401,
    "error": "Invalid provider: 'notaprovider'. Please check the model slug format: {provider_id}/{model_id}/{run_type}"
  }
}

解析时请做好防御 —— 读取 error 之前先判断它是字符串还是对象。

对话接口是个例外：POST /v1/chat/completions 和 GET /v1/models 返回的是 OpenAI 的错误结构，这样 OpenAI 客户端不用改动就能直接处理：

{
  "error": {
    "message": "...",
    "type": "invalid_request_error",
    "param": "model"
  }
}

对话接口上的鉴权失败仍然使用上面的 {"code","error"} 结构，因为这类请求在进入处理逻辑之前就被拒绝了。

HTTP 状态码

状态码	名称	说明
200	OK	请求成功
400	Bad Request	参数或请求体无效
401	Unauthorized	缺少 API Key 或 API Key 无效
402	Payment Required	余额不足，无法覆盖预估费用
403	Forbidden	账户已被封停，或提示词被内容策略拦截
404	Not Found	接口或模型 slug 不存在
500	Internal Server Error	服务端出现意外错误

Get3W 不限制每分钟请求数，也不设并发上限，因此没有 429。详见什么是账户等级。

400 —— Bad Request

请求校验失败时返回。

Error	成因
Invalid parameters	缺少必填字段，或字段类型不正确

401 —— Unauthorized

鉴权失败时返回。

Error	成因
Missing Authorization header	请求中没有 Authorization 头
Invalid Authorization format, expected: Bearer <api_key>	请求头不符合 Bearer <key> 格式
Invalid or revoked API key	Key 不存在或已被删除

402 —— Payment Required

Error	成因
Insufficient balance. Current: $X.XXX, required: $X.XXX. Please top up and try again.	账户余额低于任务的预估费用

404 —— Not Found

Error	成因
Not found	请求的接口或资源不存在

500 —— Internal Server Error

Error	成因
Server error	服务端发生了意外错误

任务错误码

任务被接受（HTTP 200）但在执行过程中失败时，任务结果里会包含 code 和 error 字段：

{
  "id": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
  "model": "google/nano-banana-pro/text-to-image",
  "status": "failed",
  "code": 1200,
  "outputs": [],
  "error": "Content moderation: prompt contains prohibited content",
  "created_at": "2026-03-28T07:50:42"
}

错误码	名称	说明
0	Success	任务成功完成
1200	Content Moderation	提示词或输入被内容审核拦截
1201	Real Person Detected	输入图片包含真实人物；请改用插画或 AI 生成的角色形象
1202	Copyright Violation	输出内容可能涉及版权限制；请避免使用受版权保护的角色、品牌或内容
1400	Missing Parameter	缺少必填参数
1401	Invalid Parameter	参数值无效或超出取值范围
1402	Media Access Failed	无法下载或访问提供的媒体 URL
1403	Task Execution Failed	任务在处理过程中出错
1405	Task Failed	通用任务失败
5000	Internal Error	系统内部错误
5003	Service Unavailable	上游模型供应商暂时不可用
5004	Timeout	等待供应商响应超时

重试策略

对于可恢复的临时性错误（HTTP 500 以及任务错误码 5000、5003、5004），建议实现指数退避重试：

import time
import requests

def api_request_with_retry(url, headers, json_data, max_retries=3):
    for attempt in range(max_retries):
        response = requests.post(url, headers=headers, json=json_data)

        if response.status_code == 200:
            return response.json()
        elif response.status_code == 500:
            wait_time = 2 ** attempt
            time.sleep(wait_time)
        else:
            response.raise_for_status()

    raise Exception("Max retries exceeded")

任务级别的临时性错误，重试方式是提交一个新任务。

下一步

• API 入门 — 完成第一次 API 调用
• API 鉴权 — 鉴权细节与账户等级