Errors
Every error status, what it means and what to do, in the words the CLI prints. Search this page for the message you see.
When a request fails, the server answers with an HTTP status and a message that says why. The CLI prints the message, then a hint. An AI assistant gets the same message from its tools. Read the message first: it names the limit, the id or the state that stopped the request.
Error (403): write scope required
This API key's access does not allow that. Use a key with "Build and evaluate" or "Full access".In Python, a failed request raises RehearsalError, with the status in .status and the message in .detail.
Over HTTP, the message is the detail field of the JSON answer.
By status
| Status | Meaning | The CLI's hint |
|---|---|---|
401 | The server does not know who is asking. The key is missing, mistyped or revoked, or a console session has ended. | Check REHEARSAL_API_KEY: the key is missing, mistyped, or revoked. Create one on the console's API keys page. |
402 | The workspace's plan does not cover the request. Nothing was started. | The workspace's plan does not cover this. See the console's Billing page for what is left and how to get more. |
403 | The key is valid, and its access does not allow this action. | This API key's access does not allow that. Use a key with "Build and evaluate" or "Full access". |
404 | No such item in this workspace. The id is wrong, or the item belongs to another workspace, or it was removed. | Check the id: list what exists with 'rehearsal apps list', 'worlds list', 'profiles list' or 'runs show'. |
409 | The request is valid, and the item is not in a state that allows it. | Not possible in the current state; the message above says why. |
422 | The arguments are not valid. | Check the arguments. |
429 | Something is still in progress, or too many requests came from one place. | Too many jobs are running in this workspace. Wait for one to finish, or stop one. |
500 and above | The server had a problem. | The server had a problem; try again, and check the server log if it persists. |
Two statuses need care:
402is not a reason to retry. The same request gets the same answer until the month renews, the plan changes, or you ask for less.429is a reason to wait. The request can succeed when the work in progress has finished.
By message
The messages below are examples with their numbers filled in. Yours has your own numbers and names.
401
| Message | What to do |
|---|---|
| invalid API key | Check the key. Create a new one on the API keys page, or run rehearsal login. |
| authentication required | Send the key in the Authorization: Bearer header. |
| session expired | Sign in to the console again. A browser session lasts 12 hours. |
402
| Message | What to do |
|---|---|
| The Free plan keeps 1 application, and this workspace has 1. Remove one on the Applications page first. | Remove an application, or change plan. |
| This workspace has used its 1 world build. A failed build can still be restarted from its page. | Restart the failed build if there is one. Otherwise add a top-up or change plan. |
| This run needs 24 episodes and the workspace has 10 left this month (renews 01 Nov). Run fewer: choose one split, fewer jobs, or one repeat. | Run fewer episodes, or add a top-up. |
| This workspace has used its $8.00 model allowance for this month, including jobs still running. It renews on the 1st; until then, stop a running job or wait for one to finish. | Wait for the 1st, or stop a job that is still running. On a paid plan, add a top-up. |
403
| Message | What to do |
|---|---|
| write scope required | Use a key with "Build and evaluate" access. The message names the scope that is missing: read, write, evaluator or admin. |
| operator admin pages need a console sign-in, not an API key | Sign in to the console as an operator admin. |
404
| Message | What to do |
|---|---|
| Run run_1a2b3c not found | List what exists, and use an id from the list. |
409
| Message | What to do |
|---|---|
| application helpdesk exists | Choose another name. |
| runs use different world versions; their graders are not comparable | Compare runs on the same world version only. |
| episode is not running | The episode has ended. Read the next waiting turn. |
| actor does not match the current external turn | Act as the actor that the turn names. |
| current external turn already has an action | One action for each turn. Read the next turn. |
| idempotency key already used for a different action | Use a new key for a new action. |
422
| Message | What to do |
|---|---|
| commit must be a full lowercase hexadecimal object ID | Give the full 40-character commit SHA, not a branch, a tag or a short SHA. |
| git source needs an HTTPS or git@host:path URL | Use the plain https:// address of the repository. |
| tool is not offered in the current external turn | Call only the tools that the turn lists. |
429
| Message | What to do |
|---|---|
| The Free plan runs 1 world build at a time, and one is in progress. Wait for it to finish, or stop it. | Wait for the build, or stop it. |
| All 2 sandboxes of the Pro plan are in use by another run. Wait for it to finish, or stop it. | Wait for the other run, or stop it. |
| this workspace already has 2 builds in progress; wait for one to finish or stop it | A limit the server's operator set. Wait, or stop one. |
| too many requests; try again later | Wait a few minutes. This protects sign-in and sign-up from repeated attempts. |
Messages from the CLI itself
These come from the rehearsal command, before or without an answer from the server.
| Message | What to do |
|---|---|
Cannot reach Rehearsal at https://rehearsalkit.xyz (ConnectError). Check the URL (rehearsal login --url ...) and that the server is running. | The address is wrong, or the server is not running. rehearsal whoami shows the address in use. |
| Rehearsal did not answer in time. Try again; long work runs as jobs, so check 'rehearsal jobs show JOB_ID'. | Try again. Work that takes long continues on the server. |
Not signed in. Run rehearsal login: it signs in to Rehearsal at https://rehearsalkit.xyz through your browser (add --url \<address> for a server of your own). In CI, set REHEARSAL_API_KEY. | Run rehearsal login. |
| This command runs a Rehearsal server, which needs the server extra | Run pip install 'rehearsal-kit[server]'. Only the commands that run a server need it. |
| The MCP server needs the mcp extra | Run pip install 'rehearsal-kit[mcp]', or start it with uvx --from "rehearsal-kit[mcp]" rehearsal mcp. |
| rehearsal: unknown command 'evaal'. Did you mean 'eval'? Run 'rehearsal --help' to see every command. | Use the suggested command. |
| The sign-in request expired or was already used. Run rehearsal login again. | Run rehearsal login again and approve within 10 minutes. |
A job that failed
A build, a run or an improvement that fails after it started is not an HTTP error. The request was accepted,
and the work stopped later. Its error is on the job: rehearsal jobs show <job_id>, the build view in the
console, or the job_status tool.
- For a build, see When a build fails.
- For a run that looks wrong, see When a result looks wrong.
- For a server you run, see Troubleshooting.
Generated from the code of rehearsal-kit 0.1.2.
Was this page helpful?