Muse Image 这类图像生成服务的 API 在设计上通常会同时返回 HTTP 状态码与业务错误码，两个字段一起读才能定位问题。多数调试卡在只看了 HTTP 状态码是 400，却忽略了响应体里关于具体字段错误的描述。
处理 Muse Image 错误码时，优先把错误码分成四类：请求参数、认证权限、配额限制、服务端状态。每一类对应的检查路径不同，但第一步都是完整记录原始响应体，并保留请求 ID。不要只依据状态码下结论，也不要修改参数前先做同条件复现。
先分清 HTTP 状态码与业务错误码
HTTP 状态码只能说明大类。例如 400 表示请求无法被解析，422 表示业务规则校验失败，401 是认证失败，429 是访问频率或配额问题，500/503 表示服务端异常。而业务错误码通常出现在 JSON 响应体的 error.code 字段，例如 INVALID_PROMPT、MISSING_PARAMETER。调试时必须把两个值合在一起看，否则容易把参数错误当成服务端故障。
按错误码类别定位检查点
对于 Muse Image 这类模型接口，错误码集中在以下范围，可以逐个排查。
参数与格式错误
检查 prompt、image_size、n_steps、seed 等参数是否有拼写错误、取值范围不对或类型不一致。有些 API 要求 prompt 长度不超过 500 字符，超限会返回 INVALID_PROMPT。建议在发送请求前用日志打印完整参数，并使用 Python 的 requests 或 curl 直接测试。
curl -i -X POST 'https://api.example.com/v1/muse/image' \
-H 'Authorization: Bearer YOUR_API_KEY' \
-H 'Content-Type: application/json' \
-d '{"prompt":"a cat","n_steps":20}'把响应保存下来，用 jq 提取 error 字段：
curl -s https://api.example.com/v1/muse/image -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -d '...' | jq '.error'认证与权限错误
当返回 401 或 FORBIDDEN 时，需要确认 API Key 是否有效、有没有漏加 Bearer 前缀、当前账号是否具备模型访问权限。有些项目会区分只读 key 和写入 key，需要检查环境变量是否被覆盖。可用一次最简单的不带敏感参数的请求来测试认证，例如只请求模型列表。
配额与速率控制错误
429 或 QUOTA_EXCEEDED 说明当前限流或余额不足。需要查看账号的配额周期、单次请求消耗的 token 数，并按官方建议实行指数退避重试。但重试只适用于 429 和 5xx，不要对 4xx 重试。
服务端状态错误
500 或 SERVICE_UNAVAILABLE 一般不是请求本身的问题，而是服务端瞬时异常。可以等待一两分钟后再请求同一条成功过的请求来验证；如果持续失败，再去查服务状态页面或联系支持。
保存请求与响应上下文
很多错误码调试不出来是因为缺少请求 ID。Muse Image API 的响应头里通常会有 x-request-id，响应体里也可能有 request_id 字段。每次失败都应记录以下内容：时间、完整 URL、请求头（不含 key）、请求体、HTTP 状态码、业务错误码、请求 ID。这些信息在提交工单或自行复盘时都不可少。
复现与最小化验证
如果某个错误码在复杂参数下出现，逐步简化：先只传必填参数，确认能成功；再加上一个参数，再测。这个过程能快速定位是哪一项触发错误。对 prompt 内容敏感的错误，可以换一个普通英文短语来排除内容审核，比如把“a sexy woman”换成“a ginger cat”。同时确认模型名是否与当前 API 版本匹配，用错模型名会得到 MODEL_NOT_FOUND。
常见错误排查顺序
- 确认请求 URL 中的模型名、版本号没有拼写错误。
- 核对 JSON 格式和参数名是否与接口文档的大小写一致。
- 查看 API Key 是否有效，账号权限是否覆盖该模型。
- 检查请求头 Content-Type 是否为 application/json。
- 若响应中出现 5xx，保存完整响应头中的 request-id，用于后续追踪。
需要结合环境确认的部分是：不同服务商对错误码的定义可能不同，例如 INVALID_ARGUMENT 有的用来描述参数格式，有的用来描述业务规则。调试时以接入 SDK 或网关映射后的错误为准，不要假设所有后端都使用同一套枚举。