Beatra 排错指南：登录、积分、超时与错误码

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

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

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

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

错误码	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	是	登录验证码邮件暂时没能发出。请稍等片刻后重新获取验证码。

积分不足

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

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

各模型的积分价格以 beatra.models.list 和 GET /v1/catalog/models 的实时数据为准；套餐和加油包见定价页。扣费和退款的规则见计费与用量。

错误码	HTTP	可重试	何时出现，怎么处理
`insufficient_balance`	402	否	积分不足：本次请求没有开始，也没有扣费。请到 https://console.beatra.ai/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`。

任务慢或超时

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

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

参数错误

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

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

错误码	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	否	分页游标格式不正确。

版本不兼容

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

手动检查：在 Skill 目录里运行 python3 scripts/mcp_client.py update --check。它只报告商店里现在的版本，不会安装任何东西。

从当初安装的地方更新，然后开一个新的智能体会话，让智能体加载新版本：

安装方式	更新方式
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>`

公开社交数据提示 schema_hash does not match the current tool。 智能体读到工具参数之后，工具的参数变了。重新调用 beatra.social.tools.get，用新的 schema_hash 和新的 client_request_id 提交。
早期接入的代码调用了 API 已不再提供的路径或选项。 对照 API 参考和 MCP 工具参考修改调用。

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

找不到任务、文件或音色

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

任务：用 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@beatra.ai，或者在控制台里点「反馈」。请附上：

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

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