错误参考

所有错误响应的结构都相同：状态码 + 机器可读的 code + 人类可读的消息 + 可选的 field（指向出问题的输入）。

错误信封

{
  "success": false,
  "error": "Content length (5000) exceeds maximum allowed (4296 characters).",
  "code": "CONTENT_TOO_LONG",
  "field": "content"
}

HTTP 状态码

状态	含义
`200`	成功
`400`	验证错误：修正输入后重试
`401`	缺少认证请求头或认证错误
`402`	用户密钥网关：缺少 Studio 套餐或 API 额度已用完
`404`	未找到端点
`413`	请求体过大（>10 MB），或通过用户密钥网关生成的文件超过 10 MB（`output_too_large`）
`422`	即使自动修正后，引擎仍无法生成可扫描的二维码（`QR_UNSCANNABLE`），或输出会超出上限（`OUTPUT_TOO_COMPLEX`）
`429`	速率限制：参见 `Retry-After`
`500`	内部错误：记录日志并重试
`503`	服务器繁忙（大量并发渲染），或 AI 提供商容量已用尽（`AI_QUOTA_EXCEEDED`）

验证错误（400）

代码	含义
`MISSING_REQUIRED_FIELD`	`content`（AI 端点为 `prompt`）为空
`CONTENT_TOO_LONG`	编码载荷超过 4296 个字符（二维码理论上限）
`INVALID_JSON`	请求体无法解析为 JSON
`INVALID_HEX`	颜色字符串不是 `#RGB`、`#RRGGBB` 或 `#RRGGBBAA`
`INVALID_FIELD_VALUE`	通用错误，具体字段见 `field`
`VALUE_OUT_OF_RANGE`	数值字段超出文档规定的范围
`LOW_CONTRAST`	前景与背景对比度 < 4:1，引擎无法自动修正
`LOGO_TOO_LARGE`	ECC 低于 H 时 `logoSizePercent` > 25
`FILE_TOO_LARGE`	multipart 上传超过 10 MB
`MULTIPART_CONFIG_MISSING`	form-data 请求中缺少 `config` 字段

认证错误（401）

代码	含义
`UNAUTHORIZED`	缺少 `X-RapidAPI-Proxy-Secret` 或其值错误
`INVALID_INTERNAL_SIGNATURE`	BFF 的 HMAC 验证失败
`INTERNAL_TS_EXPIRED`	BFF 时间戳超出 ±60 秒窗口
`LLM_API_KEY_INVALID`	你的提供商密钥无效（仅限市场 AI 端点）

用户密钥网关错误

网关 https://qr-branding.com/api/v1/*（用户 API 密钥）会使用相同的 success / error / code 信封，返回其自有的小写错误码：

状态	错误码	含义
`400`	`invalid_body`	无法解析请求体
`401`	`missing_api_key`	缺少 `X-API-Key` 头
`401`	`invalid_api_key`	密钥无法识别、已撤销或格式错误
`402`	`studio_required`	密钥有效，但账户没有有效的 Studio 额度包。包含 `docs` 和 `pricing` 链接
`402`	`out_of_api_credits`	在没有剩余 Studio 额度的情况下使用我们的密钥进行 AI 生成。包含 `docs` 和 `pricing` 链接
`413`	`payload_too_large`	请求体超过 1 MiB
`413`	`output_too_large`	生成的文件超过 10 MB。请改用 PNG 或更小的 `outputWidth`
`415`	`multipart_not_supported`	网关只接受 JSON

支付错误

POST /api/checkout（/pricing 上的购买按钮）在缺少同意时返回 { "error": "withdrawal_waiver_required" }：

状态	错误码	含义
`400`	`withdrawal_waiver_required`	未勾选付款前的复选框（同意并放弃撤回权）。请参阅价格与额度

AI 生成错误

代码	含义
`AI_GENERATION_FAILED`	LLM 未返回可用的配置，请尝试更清晰的提示词
`AI_REQUEST_TIMEOUT`	回退链中没有任何提供商在 45 秒总时限内响应（每个最多 20 秒）。返回 503；请稍后重试
`AI_QUOTA_EXCEEDED`	回退链中的所有提供商都因配额或支出上限而拒绝。返回 503；立即重试没有用，请稍后再试
`AI_CONFIG_INVALID`	LLM 返回的配置被引擎拒绝（罕见，可降低创意度后重试）
`INVALID_LLM_PROVIDER`	仅限市场：`llmProvider` 不在 `openai anthropic google mistral cohere groq xai deepseek qwen local` 中
`INVALID_LLM_MODEL`	仅限市场：`llmModel` 不是格式正确的模型 ID

输出上限错误（422）

代码	含义
`OUTPUT_TOO_COMPLEX`	该设计会生成超过 20 MB 的 SVG 或 PDF，或每边超过 5120 px 的内部栅格画布。SVG 的大小随模块数量增长：短 URL 的模板约 1.5 MB，300 个字符的 URL 约 17 MB。请导出为 PNG、缩短内容或使用更简单的模块形状

服务器错误（500/503）

代码	含义
`INTERNAL_ERROR`	意外错误，请附上请求 ID 报告给我们
`QR_GENERATION_FAILED`	渲染引擎本身抛出异常。已知时会包含出问题的字段
`SERVER_BUSY`	高分辨率并发渲染过多。请稍候重试

字段验证约束

字段	约束
`content`	1–4296 个字符
`prompt`（AI）	1–10000 个字符
`creativity`（AI）	`0.0–1.0`
`pixelsPerModule`	`1–100`
`outputWidth` / `outputHeight`	`64–4096`
`logoSizePercent`	`3–40`（ECC H 时引擎在 `25` 处软性封顶）
`moduleScale`	`0.5–1.0`
`moduleSizeVariation`	`0.0–0.15`（软性上限，再高就无法扫描）
`qrShapeRadius`	`0–50`
Logo / 背景文件大小	≤ 10 MB
Logo / 背景图片类型	PNG、JPG、GIF、BMP、WebP
SVG / PDF 文档	≤ 20 MB (`OUTPUT_TOO_COMPLEX`)
通过用户密钥网关的文件	≤ 10 MB (`output_too_large`)