code, a session’s failure.code, or a setup run’s failure_code. Messages can change; codes don’t. HTTP errors are flat objects with required code and message fields and optional details. Every code is listed in Errors.
Sign-in and the console
| Symptom | Cause | Fix |
|---|---|---|
| Sign-in is limited to approved accounts. | Your account isn’t approved for access. | Sign in with an approved account. |
| Verify your email address with your provider, then sign in again. | Your identity provider hasn’t verified your email address. | Verify it with the provider, then sign in again. |
| That sign-in link is no longer valid. | The sign-in attempt can no longer be completed. | Start again from the sign-in page. |
API keys and authentication
| Code or symptom | Cause | Fix |
|---|---|---|
401 unauthorized | The Authorization header is missing or malformed, or the key expired, was revoked, or is inactive. | Send Authorization: Bearer $RECURSION_API_KEY. Check the key’s status under API keys. |
401 right after exporting a key | The key was exported in a different shell, or copied with extra characters. | Export it in the shell that runs your code, then check it starts with rma_. |
400 invalid_request mentioning x-organization-id | A tenant-scoped key sent no x-organization-id. | Add x-organization-id: default or an organization id, or use an organization-scoped key. See API keys. |
404 not_found on every request | x-organization-id names an organization you can’t reach. | Use default, or remove the header for an organization-scoped key. |
| A key stopped working without being revoked | It expired. | Check its status, then create a new key. |
503 service_unavailable before anything ran | The key couldn’t be checked right now. | Retry shortly. |
Organizations and roles
| Code or symptom | Cause | Fix |
|---|---|---|
403 forbidden on create, update, or delete | Your organization role is read-only. | See Organizations and roles. Use an account or key with the developer or admin role. |
403 forbidden when testing an environment’s setup | Testing setup needs create and update permission, because it provisions compute. | See Organizations and roles. Use an account or key with the developer or admin role. |
Billing
| Symptom | Cause | Fix |
|---|---|---|
| Billing isn’t in the sidebar | Your tenant role isn’t billing, admin, owner, or primary owner. | Use an account with one of those roles. |
| ”The card was declined. Replace it in Stripe, then try again.” | The bank declined the charge. | Click Manage cards, choose another card, and buy again. |
Environments and setup
| Code or symptom | Cause | Fix |
|---|---|---|
422 environment_not_verified on session start | The setup script has never passed, failed, changed since it passed, or is still being tested. details.next_action names the call to make. | Run a setup test, wait for verified with stale: false, then start again. |
Setup test fails with phase: setup | The script exited with an error or timed out. | Read failed_line, failed_command, exit_code, hint, and stderr_tail. Fix the script and test again. |
| Setup test fails in another phase | A temporary problem preparing compute. | Retry once before changing the script. |
429 setup_run_limit | Your organization has too many setup runs in flight. | Wait for one in details.in_flight, or cancel it. |
409 setup_run_in_progress | A setup test is already running for this environment. | Wait for details.setup_run_id, or cancel it. |
428 precondition_required on an environment update | You changed a stored network policy, or turned on privileged access, without expected_access. | Read the environment and send its current access settings. |
| Package installs fail in setup or in the session | The environment has no internet access. | Allow the needed destinations, or set Internet access to Enabled, then test again. |
Integrations
| Code or symptom | Cause | Fix |
|---|---|---|
| Add integration is missing on Integrations | Your role can view integrations but not add them. | Ask someone with the organization developer or admin role. |
| An app’s row stays Pending setup | Nobody finished signing in to the app. | Click Connect on the row and finish the sign-in. |
| An app’s row shows Revoked, or the agent can’t reach an app | The app no longer accepts the sign-in. | Reconnect the app on Integrations. See Reconnect an app. |
| The agent can’t use a tool in an app | The tool isn’t on the app’s allow-list, or the app isn’t granted to the agent. | Add the tool with Tools on the app’s row, or grant the app to the agent, then start a new session. |
| Sessions stopped using an app after a catalog update | A tool on the allow-list was reclassified or removed. | Open Tools on the app’s row, click Remove, then Save tools. |
| Reconnect first when granting an app to an agent | The connection isn’t active. | Connect or reconnect it on Integrations. |
400 invalid_request on built_in_integrations | More than 25 entries, a non-empty tools, or a connection that isn’t an active built-in integration with at least one tool. | Read message and fix the entry. See Grant apps to an agent. |
git or gh is unauthenticated in a session | The agent version has no GitHub grant, or the session started before you saved it. | Grant GitHub on the agent and start a new session. See GitHub access. |
| git can’t reach github.com | The environment’s network policy blocks GitHub. | Allow the GitHub hosts. See Allow GitHub hosts. |
See Integrations for every integration error.
Memory, files, and automations
| Symptom or code | Cause | Fix |
|---|---|---|
| An agent’s memory shows Updates delayed | A learning run failed. | Nothing to do. It retries on its own, and existing memories stay available. See Memory. |
409 content_sha256_mismatch updating a memory | Someone changed it after you read it. | Read it again and retry with the new hash. |
413 file_quota_exceeded on upload | Your organization’s files are at their storage quota. | Delete files you no longer need. See Files. |
| The agent can’t find an attached file | It was attached mid-turn. | It’s in place on the next tool call and visible from the next turn. |
| A deliverable isn’t on the session’s Files tab | The agent saved it outside the deliverables folder. | Ask for it by name as a deliverable. See Deliverables and artifacts. |
| An automation never starts a run | It’s paused, its trigger is off, or its event source is paused. | Resume the automation and the source. See Automations. |
A webhook delivery returns 401 unauthorized | The signature didn’t match the source’s signing secret. | Sign the exact body bytes with the secret in the source’s vault. |
An automation run is failed | The session couldn’t start. | Read the run’s error, fix the named field or resource, and run it again. |
MCP servers and credentials
| Code or symptom | Cause | Fix |
|---|---|---|
| MCP tools are missing from a session | The server couldn’t be reached, its handshake failed, or no granted credential matched its URL. | Probe the server and fix the URL, server, or vault grant, then start a new session. A running session doesn’t pick up new tools. See MCP servers. |
| An environment-variable secret shows up in the transcript | The agent printed it. Any command in the sandbox can read these secrets. | Rotate the secret. Prefer an MCP credential, which never enters the sandbox. See Security. |
Session fails with credential_resolution_failed | A granted credential couldn’t be opened, or was deleted. | Check the session’s vaults and credential_refs. |
Sessions
| Code or symptom | Cause | Fix |
|---|---|---|
Session stays queued | The agent is at its max_concurrent_sessions cap. Child sessions don’t count. | Wait for a root session to finish, hard stop one you don’t need, or raise the cap. See Usage and cost. |
Session stays provisioning | Compute is being prepared. | Read the session, not just its events. After 5 minutes it fails with sandbox_provision_timeout; resume it or start again. |
No events yet, but the session is running | The event stream is written separately and can lag the session record. | Trust status and execution_state from getSession. |
Session failed | See failure.code, failure.category, and failure.retryable. | transient: send a follow-up to resume. caller_error: fix the configuration first. internal: report the session_id. See Session failure codes. |
422 sandbox_provider_disabled | The request names a runtime this deployment doesn’t offer for new work. | Use the Agent runner runtime (runs). |
Session is idle with end_turn but the work is incomplete | The agent stopped on its own. end_turn doesn’t mean correct. | Send guidance, or add an outcome so a grader checks the work. |
409 idempotency_conflict | You reused an Idempotency-Key with a different request. | Use a new key for a new request. |
Event stream returns 503 service_unavailable | The service is at event-stream capacity. | Close streams you no longer need, then retry with backoff. |
| Event stream disconnects | Networks drop long connections. | Reconnect with Last-Event-ID or after_event_id set to the last event you received. See Events. |
| A follow-up after a hard stop starts from a clean workspace | Hard stop tears down the sandbox. | Use Interrupt instead when you want to keep the sandbox. |
Grading
| Symptom | Cause | Fix |
|---|---|---|
Outcome never reaches satisfied | A criterion can’t be met, can’t be checked on its own, or needs facts the grader can’t see. With no max_iterations, the agent keeps revising. | Read the newest pass’s failed criteria and their rationale. Hard stop if needed, then define a new outcome with checkable criteria and a finite max_iterations. See Outcomes. |
Outcome ends max_iterations_reached | A criterion still failed on the last allowed pass. | Tighten the prompt or the rubric, then define a new outcome. |
Outcome ends failed | The rubric couldn’t be graded. | Rewrite it as a list of independent, checkable criteria. |
stop_reason: grader_failed | A grading pass produced no usable verdict. | Send a follow-up to retry. |
Defining an outcome returns 400 invalid_request on outcome | The session already has an active outcome. Only one runs at a time. | Wait until it’s graded, then define the next one. |
| The grader ignores facts from your message | The grader never sees the opening message, only the outcome’s objective and rubric. | Put facts the grader must check in the outcome’s description or the rubric. |
Rate limits and server errors
| Code | Cause | Fix |
|---|---|---|
429 rate_limit_exceeded | Too many requests from you, across all your keys and console use. | Retry-After tells you how long to wait, not whether replay is safe. Retry only when the operation’s strategy in Endpoints permits it and details.retryable is not false. Numeric limits aren’t published. |
503 | A dependency is temporarily unavailable, or a keyed request could not reserve its idempotency key. | Read code and details.retryable. Retry only when the operation’s strategy in Endpoints permits it. idempotency_unavailable did not run the request, so resend the same key and request bytes. |
504 gateway_timeout | The request took too long and may have run. | Retry a keyed mutation only with the same key and request bytes. Read the resource before deciding whether to repeat any other write. |
500 internal_error | An unexpected failure. | Retry reads once. For a write, follow the operation’s strategy in Endpoints. If it persists, report the request id. |
What to include in a support request
| Field | Why |
|---|---|
code | Selects the recovery path. Do not match message. |
details.field | When present, names the request field, query parameter, or header at fault. |
details | When present, holds code-specific state, measured values, limits, and next actions. |
details.retryable | When present, advises whether the failure is transient. It does not override the operation’s retry strategy. |
details.requestId, or the x-request-id header | Lets support find the request. |
session_id | Identifies the full session tree and its events. |
failure.code and failure.phase | Say which stage of a session failed. |
setup_run_id | Identifies a setup test and its log. |
recursion-organization-id response header | Confirms which organization the request ran in. |
Next steps
Errors
Every error and failure code with retry guidance.
Limits
Every limit you can hit.
Event types and states
Decode statuses, stop reasons, and results.
API conventions
Retries, idempotency, and paging.