错误与重试

下表由 Beatra 的公开错误码定义自动生成。

Beatra 的每个公开错误响应都使用统一的错误信封。error.code 取自下表中稳定的公开值；error.retryable 告诉客户端，原样重试是否有可能成功。

每个错误响应体的结构如下：

{
  "error": {
    "code": "<machine code>",
    "type": "<error family>",
    "message": "<human description>",
    "retryable": true,
    "param": "/field",
    "details": {},
    "request_id": "req_..."
  }
}

怎么分支

看到	该做
`retryable: true`	短暂退避后，可以用完全相同的请求和同一个 `Idempotency-Key` 重试。响应带有 `Retry-After` 头时请遵守；`429` 响应还会附带 `X-RateLimit-*` 头。
`retryable: false`	原样重试会得到同样的结果。客户端需要修改请求、修正凭据，或把错误展示给用户。在不可重试的错误上循环重试是 bug。
`error.param`	如有，是指向请求体中出错字段的 JSON Pointer（RFC 6901）。
`error.type` / `error.details` / `error.request_id`	分别给出稳定的错误类别、修正所需的信息和追踪标识。
`error.message`	诊断用的文字，不能作为分支依据。任务在模型服务返回后最终失败时，它会保留模型服务的原始措辞，并已做过凭据、签名 URL、控制字符和长度方面的安全处理。

如果有 error.details.recovery，它会在不改变顶层错误信封的前提下，给出可用于分支的处理动作。requires_input_change 表示提交的内容是否必须修改。client_request_id: new 表示修正后的工作或已终止的工作是一个新的逻辑请求；否则按 retryable 和该端点的幂等规则处理。

{
  "details": {
    "recovery": {
      "action": "fix_arguments_and_resubmit",
      "requires_input_change": true,
      "client_request_id": "new"
    }
  }
}

认证与账号

错误码	HTTP	可重试	何时出现，怎么处理
`unauthorized`	401	否	缺少认证凭据，或格式不正确。请发送 `Authorization: Bearer <API key>`。
`invalid_api_key`	401	否	API Key 无效、已停用、已吊销或不存在。请在控制台「开发 → API Key」创建或轮换 Key，再用新 Key 重试。
`api_key_region_mismatch`	400	否	API Key 的区域前缀与当前端点不一致。请调用与该 Key 区域对应的 API 主机，或改用为本区域签发的 Key。

展开其余 3 个

错误码	HTTP	可重试	何时出现，怎么处理
`tenant_disabled`	403	否	账号已被暂停或停用。请联系支持；重试无法成功。
`forbidden`	403	否	调用方没有执行此操作的权限。请使用具备相应权限的凭据；原样重试无法成功。
`email_send_failed`	502	是	登录验证码邮件暂时没能发出。请稍等片刻后重新获取验证码。

计费

错误码	HTTP	可重试	何时出现，怎么处理
`insufficient_balance`	402	否	积分不足：本次请求没有开始，也没有扣费。请到 https://console.beatra.ai/wallet?intent=buy 充值，积分立即生效；然后重试同一个请求。无需重新安装或重新授权。
`billing_failed`	500	是	扣费或退款在多次重试后仍失败。请用相同的 Idempotency-Key / client_request_id 重试；同一个请求标识保证不会重复扣费。
`payment_provider_unavailable`	503	否	此支付方式暂未配置收款服务。请在控制台选择其他支付方式。

容量与可用性

错误码	HTTP	可重试	何时出现，怎么处理
`rate_limited`	429	是	超出了调用方的速率限制。请在 `Retry-After` 指定的时间后重试；`X-RateLimit-*` 响应头会给出当前额度。
`model_unavailable`	503	是	所请求的模型暂时不可用。请退避后重试，或换一个可选模型（`beatra.models.list` 或 `GET /v1/catalog/models`），或使用 `model=auto`。
`model_request_failed`	502	是	模型请求在可重试的服务错误之后仍然失败。请退避后重试；如果持续出现，请调整输入或换一个模型。

展开其余 4 个

错误码	HTTP	可重试	何时出现，怎么处理
`model_timeout`	504	是	模型请求超时。请退避后重试。
`model_rate_limited`	429	是	模型容量被限流。请退避后重试。
`model_output_invalid`	502	是	模型已成功生成，但多次尝试后仍无法下载生成的结果文件。任务记为失败，没有可用的结果文件。
`internal_error`	500	是	未分类的服务端错误。请用相同的幂等标识重试；如果持续出现，请附上 request_id 反馈问题。

其他错误码

请求校验15 个 ⌄

错误码	HTTP	可重试	何时出现，怎么处理
`invalid_request`	422	否	请求体未通过结构校验。`param` 指向第一个出错的字段；`details.errors` 列出每一处错误及其 `loc` 和原因。修正这些字段后重新发送。
`skill_package_format_invalid`	422	否	Skill 包标识格式不正确。请使用不超过 64 个字符、由小写字母和连字符组成的 slug，以及合法的 SemVer 包版本号。
`unsupported_capability`	400	否	该能力不存在或已停用。`GET /v1/catalog/capabilities` 会列出当前可用的能力。
`unsupported_model`	400	否	该模型不存在，或不能用于此能力。请用 `beatra.models.list` 或 `GET /v1/catalog/models` 查询可选模型，或使用 `model=auto`。
`unsupported_option`	422	否	所选的具体模型不支持请求中的某个取值或控制项。`param` 指出字段，`details.candidate_failures[]` 给出具体失败码（如 `unsupported_resolution`、`unsupported_duration`、`unsupported_aspect_ratio`），以及收到的值和支持的值。请修改该字段或换一个模型；使用 `model=auto` 时，只有所有候选模型都无法满足请求才会返回此错误。
`no_eligible_model`	422	否	没有任何在线模型能完整满足这次 `model=auto` 请求。`details.candidate_failures[]` 列出每个候选模型的拒绝原因；只修改不兼容的字段，或选用列出的某个具体模型。
`voice_model_incompatible`	422	否	所请求的音色在所请求的模型上不可用。请使用 `model=auto`、兼容的模型，或从音色列表中另选一个音色。
`unsupported_input_modality`	422	否	所选模型不支持请求中的某种输入类型（如图片、音频或文件）。`param` 指向第一个出错的字段；请去掉它，或选用支持该输入的模型。
`context_length_exceeded`	422	否	请求超出了所选模型的上下文长度。请缩短输入，或选用上下文更长的模型。
`safety_rejected`	400	否	请求未通过内容安全审核。请让用户检查提示词和每一个输入素材，修改或替换可能不安全的内容后，用新的 client_request_id 提交新任务。原样重试不会有帮助。
`content_filtered`	502	否	生成过程中，安全过滤拦截了输出。请改写提示词或换一个模型；原样重试通常仍会被拦截。
`not_found`	404	否	请求的 HTTP 资源或端点不存在。请检查路径和标识；原样重试无法成功。
`streaming_not_yet_implemented`	501	否	旧版本兼容用的错误码：早期部署能识别 `stream=true`，但没有启用流式输出。
`invalid_window`	422	否	时间范围无效。
`invalid_cursor`	400	否	分页游标格式不正确。

回调3 个 ⌄

错误码	HTTP	可重试	何时出现，怎么处理
`callback_url_required`	422	否	选择了回调签名密钥时，必须提供回调地址。请添加 `callback_url`，或去掉 `callback_signing_key_id`。
`callback_signing_key_not_found`	404	否	回调签名密钥不存在，或当前账号无权查看。请在控制台查看签名密钥列表，并传入一个有效的密钥 ID。
`callback_signing_key_inactive`	422	否	该回调签名密钥已停用，不能用于新任务。请选择一个启用中的密钥；不需要签名时，可以不传密钥 ID。

媒体输入5 个 ⌄

错误码	HTTP	可重试	何时出现，怎么处理
`invalid_media`	422	否	媒体输入格式错误或无法解码。请重新导出或重新编码文件后再提交；`param` 指出出错的字段。
`unsupported_media_type`	422	否	此能力不支持该媒体类型。请转换为支持的格式（见能力页或模型约束）后重新发送。
`media_too_large`	413	否	媒体输入超过了大小上限。请压缩或裁剪输入，或先上传，再传入素材引用（artifact）。
`media_fetch_failed`	422	是	Beatra 无法访问某个输入资源。请确认该资源可以通过 HTTPS 访问，或先上传，再传入素材引用（artifact）。
`upload_stalled`	408	是	上传太久没有发送数据，或超过了上传时长上限。请向同一个上传地址重新发送同一个 PUT；如果上传授权已过期，请用 `beatra.assets.upload` 重新申请一个。

任务与资源11 个 ⌄

错误码	HTTP	可重试	何时出现，怎么处理
`task_not_found`	404	否	task_id 不存在，或不属于当前账号。请使用创建任务时返回的 task_id；可以用 `GET /v1/tasks` 或 `beatra.tasks.list` 列出最近的任务。
`conflict`	409	否	操作与资源的当前状态冲突；对于取消任务，这表示任务会继续执行。请按 `details.action` 处理（通常是继续轮询同一个任务），不要重新提交。
`result_undeliverable`	502	否	已完成的结果无法返回：体积过大、嵌套过深，或不是合法的 JSON。不要重复提交同样的查询。
`artifact_not_found`	404	否	artifact_id 不存在，或不属于当前账号。请重新上传媒体，并使用新返回的 artifact ID。
`voice_not_found`	404	否	voice_id 不存在，或不属于当前账号。可以用 `GET /v1/voices` 或 `beatra.voices.list` 列出可用音色。
`voice_activation_required`	422	否	这个音色还是免费试听，激活后才能用于语音合成。请先向用户确认激活价格，再调用 `beatra.voices.activate`。
`price_confirmation_required`	422	否	激活报价已过期或已变化。请把新报价告知用户并取得同意，然后用新的 `confirmation_token` 和 `confirm_credits` 再次调用 `beatra.voices.activate`。
`voice_preview_expired`	422	否	这个试听音色已过期，不能再激活或用于合成。请重新克隆。
`voice_sample_rejected`	422	否	声音样本被拒绝。请查看 `details.reason`，修正样本后用新的 `client_request_id` 重新克隆。
`voice_limit_reached`	409	否	这个账号等待激活的克隆音色已达上限。请激活一个，或在桌面端删除一个，也可以用 `DELETE /v1/voices/{voice_id}` 删除；等待中的音色 7 天后也会过期。
`voice_activation_daily_limit`	429	否	这个账号今天已激活 3 个克隆音色，达到每日上限，本次未扣费。如需今天继续激活，请联系 Beatra 客服；上限在 UTC 00:00（北京时间 08:00）重置。

幂等与响应模式2 个 ⌄

错误码	HTTP	可重试	何时出现，怎么处理
`idempotency_conflict`	409	否	同一个 `Idempotency-Key` / `client_request_id` 用在了不同的请求体上。修改过的请求请换一个新标识；要原样重试同一个请求，就复用原标识。决定之前，先查看已有的任务。
`request_in_progress`	409	是	同一个幂等标识对应的请求还在处理中。请稍后用同一个标识重试，会拿到原请求的响应。

一次生成可能被成功受理，之后以 status: failed 结束。REST 任务查询、MCP beatra.tasks.get 和回调返回同一个 Task.error 对象，包含 code、type、message、retryable，以及可选的 param、details 和 request_id。读到失败的任务，说明任务已到最终状态，不是 MCP 协议错误。

model_output_invalid 表示模型已成功生成，但 Beatra 多次尝试后仍无法下载生成的结果文件。这个失败的任务没有可用的结果文件。

MCP 工具错误

MCP 工具调用失败时，返回 isError: true 的工具结果，structuredContent.error 使用与 REST 错误信封相同的字段：code、type、message、retryable、可选的 param（指向工具参数的 JSON Pointer）、可选的 details，另加 JSON-RPC 的 jsonrpc_code。请和 REST 一样按 code 与 retryable 分支处理。

只有一个 MCP 专有错误码：insufficient_scope，表示 OAuth 授权缺少所需的 scope，missing_scopes 会列出缺少的项。请重新运行 Beatra 设备授权；不重新授权就重试不可能成功。意外的服务端故障会以 internal_error 工具结果返回，不会是裸 HTTP 错误。

本页由 52 个公开错误码生成。另有 25 个内部、管理端或服务商接入专用的错误码，不在公开文档中列出。

怎么分支

认证与账号

计费

容量与可用性

其他错误码

异步任务失败

MCP 工具错误

本页内容