Beatra troubleshooting: sign-in, credits, timeouts, errors

Every Beatra failure carries an error code and a retryable flag: in a REST error body, in a failed MCP tool result, and in a failed task. Find the symptom below and work through its steps in order. Each section ends with the error codes that belong to it and what to do about each one. The error envelope and the retry rules are on Errors & retries.

Sign-in fails

Agents sign in to Beatra once, in the browser: the Beatra Skill requests a device code, opens an approval page, and waits while you approve. Its sign-in helper, scripts/authorize.py in the installed Skill folder, prints Beatra is ready when the connection works.

1. The helper printed BEATRA_AUTH_PENDING. The approval is still open. Open the approval link it printed, sign in, and choose Allow, then let the agent run the same command again. Every run continues the same approval, so you approve only once. An approval page stays open for up to an hour.
2. The helper printed access_denied or expired_token. The approval was declined, or the page expired before Allow was chosen. Ask the agent to run python3 scripts/authorize.py again for a new approval page.
3. Beatra worked before and now reports BEATRA_AUTH_REQUIRED. The sign-in on this computer has ended: it was unused for 15 days, or the computer was disconnected under Devices in the console. Ask the agent to run python3 scripts/authorize.py again and approve once.
4. A tool call returns insufficient_scope. The connection lacks access a tool needs, and missing_scopes names it. Reconnect with python3 scripts/authorize.py --force and approve once. Retrying without reconnecting returns the same error.
5. The sign-in page will not load, or a verification code never arrives. Sign-in troubleshooting covers the WeChat QR code, email and phone codes, and signing in to the wrong account.
6. Your own app gets 401. Send Authorization: Bearer <API key> with a key from the console (Developer → API keys), on the API host that matches the key's region. See Authentication & request conventions.

Not enough credits

Paid tools check the balance before they start. When it is short, the call returns insufficient_balance (HTTP 402): the work did not start and nothing was charged.

1. Top up in the console at console.beatra.ai/wallet. Credits take effect immediately. The wallet's "Adding credits to: …" line names the account that receives them.
2. Retry the same request unchanged: the same arguments and the same client_request_id or Idempotency-Key. No reinstall or new sign-in is needed.
3. In an agent, tell it you have topped up. After a refusal, the Beatra Skill answers further calls to the same tool on this computer with the same message (details.local_hold) until you say you have topped up, so a long batch stops at the first refusal. The hold also lifts by itself after 30 minutes.
4. The top-up went through but the balance has not moved. The credits most likely went to another account. Open the top-up link from the agent again and check "Adding credits to: …", or merge the two accounts: see Accounts and merging.
5. The balance is negative after a task. A task's measured usage can exceed its estimate. The result stays valid; new paid work waits for a top-up.

Prices per model are live in beatra.models.list and GET /v1/catalog/models; plans and top-up packs are on the pricing page. How charging and refunds work: Billing & usage.

Slow tasks and timeouts

Generation runs as an asynchronous task: queued, then running, then succeeded, failed, or canceled. A task that is still queued or running is working, and the result arrives when it reaches a final state.

1. The task is still queued or running. Keep checking the same task with beatra.tasks.get or GET /v1/tasks/{task_id}, about every 5 seconds. Submitting the request again creates a second task that is billed separately.
2. progress.stage is finalizing. The model has finished and Beatra is storing the files. Beatra keeps trying to fetch them for up to about 40 minutes without generating or charging again. If they still cannot be fetched, the task fails with model_output_invalid and its credits are refunded.
3. The call timed out or the connection dropped. Retry with the same client_request_id (MCP) or Idempotency-Key (REST) and exactly the same arguments: Beatra returns the original task instead of starting a new one. If the task ID was lost, list recent tasks with beatra.tasks.list or GET /v1/tasks first.
4. The error has retryable: true. Wait for the Retry-After interval when there is one, then retry the same request. 429 responses carry X-RateLimit-* headers; see Rate limits.
5. Your plan's creations in progress are all in use. A new request does not start and nothing is charged. Wait for one to finish and retry the same request; see How many at a time.
6. model_unavailable. Pick another model from beatra.models.list, or use model: "auto" so Beatra picks one that is available.
7. Cancel returned 409. Execution has started and continues. Keep checking the same task until it reaches a final state.

Invalid parameters

A rejected request names the field: error.param is a JSON Pointer to it, and details.errors (validation) or details.candidate_failures[] (model options) say what each field accepts.

1. Change the named field and send the corrected request with a new client_request_id. The inputs changed, so it is new work; reusing the old identity returns idempotency_conflict.
2. Check the model's current limits (resolution, duration, aspect ratio, input types) in beatra.models.list or GET /v1/catalog/models, or use model: "auto" so Beatra picks a model that supports the whole request. A model you name explicitly is never replaced.
3. Media inputs: pass an HTTPS URL Beatra can reach, or upload the file with beatra.assets.upload and pass the artifact ID it returns. See Upload source media.
4. Content review: safety_rejected and content_filtered mean the prompt or an input needs to change. The same content is rejected again.
5. Argument lists: every MCP tool's arguments are in the MCP tool reference, and every REST body in the API reference.

Version mismatch

The Beatra Skill on your computer stays at the version you installed until you update it. At most once a day it checks the store or tool you installed it from, and when a newer version is there it prints one line with the command that updates it.

1. Check by hand from the installed Skill folder with python3 scripts/mcp_client.py update --check. It reports what your store offers and installs nothing.

2. Update through the place you installed from, then start a new agent session so the agent loads the new version:

   Installed with	Update with
   The Beatra install message	Send the install message again
   skills CLI	npx skills update <package> -g -y for a global install, or npx skills update <package> -p -y in the project folder
   GitHub CLI	gh skill update <package>
   ClawHub CLI	clawhub update <package> --workdir <dir> --dir <skills-dir>
   SkillHub CLI	skillhub install <package> --force --dir <skills-dir>
   WorkBuddy	Update the Skill in WorkBuddy

3. Public social data says schema_hash does not match the current tool. The tool's arguments changed after the agent read them. Call beatra.social.tools.get again and submit with the new schema_hash and a new client_request_id.

4. An older integration calls a path or option the API no longer serves. Compare the call with the API reference and the MCP tool reference.

Missing tasks, files, and voices

A *_not_found code means the ID does not exist, or it belongs to another Beatra account. Use the ID returned when the task, file, or voice was created, and check that the agent or API key belongs to the account that created it (Accounts and merging).

• Tasks: list recent ones with beatra.tasks.list or GET /v1/tasks.
• Uploaded files: upload the file again and use the new artifact ID.
• Voices: list the voices you can use with beatra.voices.list or GET /v1/voices. A cloned voice that waits for activation expires after 7 days.

Still stuck

Email support@beatra.ai, or use Feedback in the console. Include:

• the request_id from the error (the same value as the X-Request-Id response header), and the task ID when there is one;
• the error code and message;
• when it happened, and whether you used the Skill, MCP, or the REST API.

Support needs none of your API keys, the files under ~/.beatra/, or verification codes; leave them out.