# Beatra 排错指南：登录、积分、超时与错误码
> 登录失败、积分不足、任务慢或超时、参数错误、版本不兼容、找不到任务或文件，按现象逐步处理，附全部错误码的含义和处理方法。

Beatra 的每一次失败都带着错误码 `code` 和是否可重试的 `retryable`：REST 的错误响应、MCP 工具调用的失败结果、失败的任务里都有。先在下面找到和你遇到的现象对应的一节，按顺序逐步处理；每一节末尾列出属于这一类的错误码，以及每个错误码的处理方法。错误响应的结构和重试规则见[错误与重试](https://docs.beatra.cn/zh/docs/mechanisms/errors)。

## 登录失败 [#sign-in]

智能体只需要在浏览器里登录 Beatra 一次：Beatra Skill 申请一个设备码，打开授权页面，等你批准。Skill 目录里的登录助手 `scripts/authorize.py` 在连接可用时会输出 `Beatra is ready`。

1. **助手输出了 `BEATRA_AUTH_PENDING`。** 授权还没完成。打开它给出的授权链接，登录后点「允许连接」，再让智能体把同一条命令运行一次。每次运行接着的都是同一个授权，所以你只需要批准一次。授权页面最长可以保持一小时。
2. **助手输出了 `access_denied` 或 `expired_token`。** 授权被拒绝了，或者页面在点「允许连接」之前就过期了。让智能体重新运行 `python3 scripts/authorize.py`，打开新的授权页面。
3. **之前能用，现在提示 `BEATRA_AUTH_REQUIRED`。** 这台电脑上的登录已经失效：连续 15 天没有使用，或者在[控制台](https://console.beatra.cn/agents)的「设备」里断开了这台电脑。让智能体重新运行 `python3 scripts/authorize.py`，批准一次即可。
4. **工具调用返回 `insufficient_scope`。** 当前连接缺少某个工具需要的权限，`missing_scopes` 会写明缺哪些。用 `python3 scripts/authorize.py --force` 重新连接并批准一次；不重新连接就重试，结果还是同一个错误。
5. **登录页打不开，或者收不到验证码。** 见[登录问题排查](https://docs.beatra.cn/zh/docs/sign-in-help)，里面有微信二维码、邮箱和手机验证码、登录到别的账号这几种情况的处理步骤。
6. **自己开发的应用收到 `401`。** 请求头带上 `Authorization: Bearer <API key>`，Key 在控制台「开发 → API Key」里创建，并调用与 Key 区域对应的 API 主机。见[认证与请求约定](https://docs.beatra.cn/zh/docs/authentication)。

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

## 积分不足 [#credits]

付费工具在开始前先检查余额。余额不够时返回 `insufficient_balance`（HTTP 402）：任务没有开始，也没有扣费。

1. **到控制台充值**：[console.beatra.cn/wallet](https://console.beatra.cn/wallet?intent=buy)。积分立即生效。钱包里「充值到：…」这一行写明了积分充进哪个账号。
2. **原样重试同一个请求**：参数不变，`client_request_id` 或 `Idempotency-Key` 也不变。不需要重新安装，也不需要重新登录。
3. **在智能体里，充值后告诉它一声。** 被拒一次后，Beatra Skill 在这台电脑上对同一个工具的后续调用都会直接回复同样的提示（`details.local_hold`），直到你说已经充值。所以批量任务会停在第一次被拒的地方。30 分钟后这个限制也会自动解除。
4. **充值成功了，余额却没变。** 积分很可能充进了另一个账号。重新打开智能体给的充值链接，看「充值到：…」写的是哪个账号；或者把两个账号合并，见[账号与合并](https://docs.beatra.cn/zh/docs/accounts#merge)。
5. **任务完成后余额变成负数。** 任务实际用量可能超过预估。成品照常有效，新的付费任务要等充值后再做。

各模型的积分价格以 `beatra.models.list` 和 `GET /v1/catalog/models` 的实时数据为准；套餐和加油包见[定价页](https://www.beatra.cn/zh/pricing)。扣费和退款的规则见[计费与用量](https://docs.beatra.cn/zh/docs/mechanisms/billing)。

| 错误码 | HTTP | 可重试 | 何时出现，怎么处理 |
|---|---|---|---|
| `insufficient_balance` | 402 | 否 | 积分不足：本次请求没有开始，也没有扣费。请到 https://console.beatra.cn/wallet?intent=buy 充值，积分立即生效；然后重试同一个请求。无需重新安装或重新授权。 |
| `billing_failed` | 500 | 是 | 扣费或退款在多次重试后仍失败。请用相同的 Idempotency-Key / client_request_id 重试；同一个请求标识保证不会重复扣费。 |
| `payment_provider_unavailable` | 503 | 否 | 此支付方式暂未配置收款服务。请在控制台选择其他支付方式。 |
| `voice_activation_required` | 422 | 否 | 这个音色还是免费试听，激活后才能用于语音合成。请先向用户确认激活价格，再调用 `beatra.voices.activate`。 |
| `price_confirmation_required` | 422 | 否 | 激活报价已过期或已变化。请把新报价告知用户并取得同意，然后用新的 `confirmation_token` 和 `confirm_credits` 再次调用 `beatra.voices.activate`。 |

## 任务慢或超时 [#timeouts]

生成以异步任务运行：先是 `queued`（排队中），再是 `running`（生成中），最后是 `succeeded`、`failed` 或 `canceled`。任务还在 `queued` 或 `running`，说明它正在处理，到达最终状态时会给出结果。

1. **任务还在 `queued` 或 `running`。** 用 `beatra.tasks.get` 或 `GET /v1/tasks/{task_id}` 继续查询同一个任务，间隔约 5 秒。重新提交同一个请求会建出第二个任务，单独计费。
2. **`progress.stage` 是 `finalizing`。** 模型已经生成完，Beatra 正在保存文件。Beatra 会在约 40 分钟内反复尝试取回文件，不会重新生成，也不会再次扣费；仍然取不回时，任务以 `model_output_invalid` 失败，积分退回。
3. **调用超时或者连接断了。** 用相同的 `client_request_id`（MCP）或 `Idempotency-Key`（REST）和完全相同的参数重试：Beatra 会返回原来的任务，不会新建。任务 ID 丢了的话，先用 `beatra.tasks.list` 或 `GET /v1/tasks` 查最近的任务。
4. **错误里 `retryable: true`。** 有 `Retry-After` 时等够这段时间，再重试同一个请求。`429` 响应带有 `X-RateLimit-*` 头，见[限流](https://docs.beatra.cn/zh/docs/mechanisms/rate-limits)。
5. **套餐允许同时进行的任务都在跑。** 新请求不会开始，也不会扣费。等一个任务完成后重试同一个请求，见[同时做几个](https://docs.beatra.cn/zh/docs/mechanisms/billing#同时做几个)。
6. **`model_unavailable`。** 从 `beatra.models.list` 换一个模型，或者用 `model: "auto"`，让 Beatra 选一个可用的模型。
7. **取消任务返回 `409`。** 任务已经开始执行，会继续跑完。继续查询同一个任务，直到最终状态。

| 错误码 | HTTP | 可重试 | 何时出现，怎么处理 |
|---|---|---|---|
| `model_timeout` | 504 | 是 | 模型请求超时。请退避后重试。 |
| `model_request_failed` | 502 | 是 | 模型请求在可重试的服务错误之后仍然失败。请退避后重试；如果持续出现，请调整输入或换一个模型。 |
| `model_unavailable` | 503 | 是 | 所请求的模型暂时不可用。请退避后重试，或换一个可选模型（`beatra.models.list` 或 `GET /v1/catalog/models`），或使用 `model=auto`。如有 `details.reason` 和 `details.available_at`，分别说明原因和预计恢复时间。 |
| `model_rate_limited` | 429 | 是 | 模型容量被限流。请退避后重试。 |
| `rate_limited` | 429 | 是 | 超出了调用方的速率限制。请在 `Retry-After` 指定的时间后重试；`X-RateLimit-*` 响应头会给出当前额度。 |
| `voice_activation_daily_limit` | 429 | 否 | 这个账号今天已激活 3 个克隆音色，达到每日上限，本次未扣费。如需今天继续激活，请联系 Beatra 客服；上限在 UTC 00:00（北京时间 08:00）重置。 |
| `request_in_progress` | 409 | 是 | 同一个幂等标识对应的请求还在处理中。请稍后用同一个标识重试，会拿到原请求的响应。 |
| `conflict` | 409 | 否 | 操作与资源的当前状态冲突；对于取消任务，这表示任务会继续执行。请按 `details.action` 处理（通常是继续轮询同一个任务），不要重新提交。 |
| `upload_stalled` | 408 | 是 | 上传太久没有发送数据，或超过了上传时长上限。请向同一个上传地址重新发送同一个 PUT；如果上传授权已过期，请用 `beatra.assets.upload` 重新申请一个。 |
| `model_output_invalid` | 502 | 是 | 模型返回的结果无法交付，例如音频缺失或损坏，或生成的文件无法取回。任务失败并退款，请重新提交。 |
| `internal_error` | 500 | 是 | 未分类的服务端错误。请用相同的幂等标识重试；如果持续出现，请附上 request_id 反馈问题。 |

## 参数错误 [#invalid-parameters]

被拒绝的请求会指出是哪个字段：`error.param` 是指向该字段的 JSON Pointer，`details.errors`（校验失败）或 `details.candidate_failures[]`（模型不支持的选项）写明每个字段接受什么值。

1. **改掉指出的字段，用新的 `client_request_id` 发送修改后的请求。** 输入变了就是新任务；沿用旧的请求标识会返回 `idempotency_conflict`。
2. **查模型当前的限制**（分辨率、时长、画面比例、输入类型）：用 `beatra.models.list` 或 `GET /v1/catalog/models`；或者用 `model: "auto"`，让 Beatra 选一个能满足整个请求的模型。你明确指定的模型不会被替换。
3. **媒体输入**：传一个 Beatra 能访问的 HTTPS 地址，或者先用 `beatra.assets.upload` 上传文件，再传它返回的 `artifact_id`。见[上传源素材](https://docs.beatra.cn/zh/docs/mechanisms/uploads)。
4. **内容审核**：`safety_rejected` 和 `content_filtered` 表示提示词或某个输入需要修改；内容不变，重试仍会被拒。
5. **参数清单**：每个 MCP 工具的参数见 [MCP 工具参考](https://docs.beatra.cn/zh/docs/mcp-tools)，每个 REST 请求体见 [API 参考](https://docs.beatra.cn/zh/docs/api-reference)。

| 错误码 | HTTP | 可重试 | 何时出现，怎么处理 |
|---|---|---|---|
| `invalid_request` | 422 | 否 | 请求体未通过结构校验。`param` 指向第一个出错的字段；`details.errors` 列出每一处错误及其 `loc` 和原因。修正这些字段后重新发送。 |
| `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 | 否 | 请求超出了所选模型的上下文长度。请缩短输入，或选用上下文更长的模型。 |
| `invalid_media` | 422 | 否 | 媒体输入格式错误或无法解码。请重新导出或重新编码文件后再提交；`param` 指出出错的字段。 |
| `unsupported_media_type` | 422 | 否 | 此能力不支持该媒体类型。请转换为支持的格式（见能力页或模型约束）后重新发送。 |
| `media_too_large` | 413 | 否 | 媒体输入超过了大小上限。请压缩或裁剪输入，或先上传，再传入素材引用（artifact）。 |
| `media_fetch_failed` | 422 | 是 | Beatra 无法访问某个输入资源。请确认该资源可以通过 HTTPS 访问，或先上传，再传入素材引用（artifact）。 |
| `safety_rejected` | 400 | 否 | 请求未通过内容安全审核。请让用户检查提示词和每一个输入素材，修改或替换可能不安全的内容后，用新的 client_request_id 提交新任务。原样重试不会有帮助。 |
| `content_filtered` | 502 | 否 | 生成过程中，安全过滤拦截了输出。请改写提示词或换一个模型；原样重试通常仍会被拦截。 |
| `idempotency_conflict` | 409 | 否 | 同一个 `Idempotency-Key` / `client_request_id` 用在了不同的请求体上。修改过的请求请换一个新标识；要原样重试同一个请求，就复用原标识。决定之前，先查看已有的任务。 |
| `callback_url_required` | 422 | 否 | 选择了回调签名密钥时，必须提供回调地址。请添加 `callback_url`，或去掉 `callback_signing_key_id`。 |
| `callback_signing_key_not_found` | 404 | 否 | 回调签名密钥不存在，或当前账号无权查看。请在控制台查看签名密钥列表，并传入一个有效的密钥 ID。 |
| `callback_signing_key_inactive` | 422 | 否 | 该回调签名密钥已停用，不能用于新任务。请选择一个启用中的密钥；不需要签名时，可以不传密钥 ID。 |
| `invalid_window` | 422 | 否 | 时间范围无效。 |
| `invalid_cursor` | 400 | 否 | 分页游标格式不正确。 |

## 版本不兼容 [#version-mismatch]

装在你电脑上的 Beatra Skill 会一直停留在安装时的版本，直到你更新它。它每天最多检查一次你当初安装它的商店或工具；那里有新版本时，会输出一行提示，写明更新命令。

1. **手动检查**：在 Skill 目录里运行 `python3 scripts/mcp_client.py update --check`。它只报告商店里现在的版本，不会安装任何东西。
2. **从当初安装的地方更新**，然后开一个新的智能体会话，让智能体加载新版本：

   | 安装方式 | 更新方式 |
   | --- | --- |
   | Beatra 安装消息 | 把安装消息再发一次 |
   | WorkBuddy | 在 WorkBuddy 里更新这个 Skill |
   | SkillHub 命令行 | `skillhub install <package> --force --dir <skills-dir>` |
   | skills 命令行 | 全局安装用 `npx skills update <package> -g -y`；装在项目里的，在项目目录运行 `npx skills update <package> -p -y` |
   | GitHub 命令行 | `gh skill update <package>` |
   | ClawHub 命令行 | `clawhub update <package> --workdir <dir> --dir <skills-dir>` |

3. **公开社交数据提示 `schema_hash does not match the current tool`。** 智能体读到工具参数之后，工具的参数变了。重新调用 `beatra.social.tools.get`，用新的 `schema_hash` 和新的 `client_request_id` 提交。
4. **早期接入的代码调用了 API 已不再提供的路径或选项。** 对照 [API 参考](https://docs.beatra.cn/zh/docs/api-reference) 和 [MCP 工具参考](https://docs.beatra.cn/zh/docs/mcp-tools) 修改调用。

| 错误码 | HTTP | 可重试 | 何时出现，怎么处理 |
|---|---|---|---|
| `skill_package_format_invalid` | 422 | 否 | Skill 包标识格式不正确。请使用不超过 64 个字符、由小写字母和连字符组成的 slug，以及合法的 SemVer 包版本号。 |
| `streaming_not_yet_implemented` | 501 | 否 | 旧版本兼容用的错误码：早期部署能识别 `stream=true`，但没有启用流式输出。 |
| `not_found` | 404 | 否 | 请求的 HTTP 资源或端点不存在。请检查路径和标识；原样重试无法成功。 |

## 找不到任务、文件或音色 [#missing-resources]

`*_not_found` 类错误码表示这个 ID 不存在，或者属于另一个 Beatra 账号。请使用创建任务、文件或音色时返回的 ID，并确认智能体或 API Key 连接的是创建它的那个账号（见[账号与合并](https://docs.beatra.cn/zh/docs/accounts)）。

- 任务：用 `beatra.tasks.list` 或 `GET /v1/tasks` 查看最近的任务。
- 上传的文件：重新上传，使用新返回的 `artifact_id`。
- 音色：用 `beatra.voices.list` 或 `GET /v1/voices` 查看可用的音色。等待激活的克隆音色 7 天后过期。

| 错误码 | HTTP | 可重试 | 何时出现，怎么处理 |
|---|---|---|---|
| `task_not_found` | 404 | 否 | task_id 不存在，或不属于当前账号。请使用创建任务时返回的 task_id；可以用 `GET /v1/tasks` 或 `beatra.tasks.list` 列出最近的任务。 |
| `artifact_not_found` | 404 | 否 | artifact_id 不存在，或不属于当前账号。请重新上传媒体，并使用新返回的 artifact ID。 |
| `result_undeliverable` | 502 | 否 | 已完成的结果无法返回：体积过大、嵌套过深，或不是合法的 JSON。不要重复提交同样的查询。 |
| `voice_not_found` | 404 | 否 | voice_id 不存在，或不属于当前账号。可以用 `GET /v1/voices` 或 `beatra.voices.list` 列出可用音色。 |
| `voice_preview_expired` | 422 | 否 | 这个试听音色已过期，不能再激活或用于合成。请重新克隆。 |
| `voice_sample_rejected` | 422 | 否 | 声音样本被拒绝。请查看 `details.reason`，修正样本后用新的 `client_request_id` 重新克隆。 |
| `voice_limit_reached` | 409 | 否 | 这个账号等待激活的克隆音色已达上限。请激活一个，或在桌面端删除一个，也可以用 `DELETE /v1/voices/{voice_id}` 删除；等待中的音色 7 天后也会过期。 |
| `voice_retired` | 422 | 否 | 该音色已下线。details 可能给出 replacement_voice_id 作为推荐替代音色；Beatra 不会自动替换音色。本次未扣费或已退款。 |
| `voice_unavailable` | 422 | 否 | 该克隆音色已无法用保存的样本恢复。这是永久性的，请勿重试，请联系客服。本次请求不收费或已退款；原克隆费用不退。 |

## 还是解决不了 [#support]

发邮件到 [support@beatra.ai](mailto:support@beatra.ai)，或者在[控制台](https://console.beatra.cn)里点「反馈」。请附上：

- 错误里的 `request_id`（与响应头 `X-Request-Id` 相同），有任务时附上任务 ID；
- 错误码 `code` 和提示文字；
- 发生的时间，以及你用的是 Skill、MCP 还是 REST API。

客服不需要你的 API Key、`~/.beatra/` 里的文件或验证码，请不要发送。