> ## Documentation Index
> Fetch the complete documentation index at: https://docs.orcapods.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix common setup, model, tool, stream, and output problems.

Find your symptom below. Most problems in a new setup are one of the first three.

## Setup

<AccordionGroup>
  <Accordion title="The client has no beta.agents attribute">
    The installed `openai` package is too old, or your code is running in a different environment from the one you installed into. Install the versions from the [quickstart](/quickstart) (`pip show openai` or `npm ls openai` shows what is installed) and restart long-running processes.
  </Accordion>

  <Accordion title="401 Unauthorized">
    The API key is missing, wrong, or revoked, or it is an OpenAI key. Orca needs an **Orca** key, sent as `Authorization: Bearer ...`. Look for stray whitespace or quotes in the environment variable.
  </Accordion>

  <Accordion title="404 on every request">
    The base URL must be `https://api.orcapods.ai/v1`. Do not add `/agents`; the client adds it. Orca's own extensions are the exception: they live at `https://api.orcapods.ai` without `/v1`, such as `/api/providers`.

    A 404 on one specific resource means it does not exist, was deleted, or belongs to another account.
  </Accordion>

  <Accordion title="Connection refused or TLS errors">
    Check that the URL is `https://api.orcapods.ai/v1`, spelled exactly, with `https://`.
  </Accordion>

  <Accordion title="403 permission_denied">
    "This action requires the admin role". Setting provider keys, writing vaults and credentials, buying credit, and changing the plan need an admin. Ask an admin of your organization, or have them change your role. See [organizations and roles](/organizations).
  </Accordion>

  <Accordion title="429 rate_limit_exceeded">
    "Your plan runs 1 session at once" (or 5, or 20): your organization already has as many sessions with a running turn as your plan allows. Send the message again when one ends, or [upgrade](/plans#sessions-at-once). "Rate limit reached. Retry after N seconds." means too many requests in a minute; wait that long, as the `Retry-After` header says.
  </Accordion>

  <Accordion title="429 insufficient_quota">
    "Out of Orca credit: add credit, then continue the session". Your balance is under the \$0.50 minimum, so Orca credit models and managed sandboxes are paused. [Add credit](/wallet#buy-credit), or use a model on your own key in a session without a sandbox.
  </Accordion>
</AccordionGroup>

## Models

<AccordionGroup>
  <Accordion title="The turn fails with a model error">
    Read `turn.error`. Common causes: a model the provider no longer offers, or a credit running out: `usage_limit_exceeded` with `param` `orca_credit` (your Orca credit) or `provider_quota` (your own provider account is out of quota). A model on your own key never falls back to Orca credit. Top up that side, or [switch the session](/providers#switch-who-pays-for-one-session) to a model on the other side with `POST /api/sessions/{session_id}/model`. See [models and provider keys](/providers).
  </Accordion>

  <Accordion title="400 on agent.model or model">
    A model name must say who pays: `orca/openrouter/<OpenRouter id>` for Orca credit, or `<provider>/<id>` with your own key. A bare name such as `gpt-5` is refused, and so is a model on your own key when no key for that provider is stored, and a model its provider does not list. Without that provider's key, the message names the key to add and, when OpenRouter offers the model, its `orca/openrouter/` name for Orca credit. With the key saved, "This is OpenRouter's name for the model" means the provider doesn't list that id: use the `orca/openrouter/` or `openrouter/` form it suggests, or the provider's own id. `GET /api/models` lists every name you can use. See [models and provider keys](/providers).
  </Accordion>

  <Accordion title="An Orca-Warning header on a save">
    The provider's model list could not be read, so the model was saved without being checked. Check the name against `GET /api/models`; a wrong name fails when a turn runs.
  </Accordion>

  <Accordion title="409 when switching a session's model">
    A turn is running, or waiting for your function results. Switch once it ends.
  </Accordion>

  <Accordion title="400 on an agent setting">
    Some settings are not available with every provider. `GET /api/providers` lists each provider's `unsupported_agent_fields`. The `param` field of the error names the setting.
  </Accordion>
</AccordionGroup>

## Turns

<AccordionGroup>
  <Accordion title="I read the history right after sending and the reply is missing">
    Sending returns before the agent answers. Wait for the turn to end first. See [turns and statuses](/turn-lifecycle).
  </Accordion>

  <Accordion title="A turn seems stuck">
    Check `sessions.retrieve(session_id)`:

    * `requires_action` with a `function_call`: your application has to send the tool result. See [function tools](/guides/function-tools).
    * `requires_action` with `environment_connection`: your self-hosted executor is not connected.
    * `in_progress`: the agent is still working. Long tasks in a sandbox can take minutes. Look at the newest items to see what it is doing.

    Do not resend the message; that adds it to the running turn or starts a second one. To stop, [cancel](/guides/streaming#cancel-a-turn).
  </Accordion>

  <Accordion title="My follow-up seems to finish instantly with the old answer">
    Your wait loop is seeing the previous turn, which is already `completed`. If the previous turn had ended before you sent the follow-up, remember its ID and wait for a turn with a different ID. (If it was still running, your message joined it, and no new turn appears.) Also skip subagent turns, which have a `subagent_id`.
  </Accordion>

  <Accordion title="The session is idle but nothing happened">
    `idle` only means no turn is running. Check the newest turn's status and `error`.
  </Accordion>

  <Accordion title="The stream disconnected">
    The turn keeps running. Read its status, then reconnect if needed. See [streaming](/guides/streaming#reconnecting-after-a-drop).
  </Accordion>
</AccordionGroup>

## Tools and environments

<AccordionGroup>
  <Accordion title="Session creation fails with an MCP error">
    "Destination is not enabled in the server egress policy" means the server was refused: remote MCP servers are currently blocked on hosted Orca. Write to [support@okik.io](mailto:support@okik.io) if you need one. Otherwise, the URL is not HTTPS, the server is unreachable, or no attached vault has a credential for that exact URL. See [MCP tools](/guides/mcp#troubleshooting).
  </Accordion>

  <Accordion title="The agent says it cannot run code">
    The session has `environment: {"type": "none"}`. Create a new session with a sandbox. See [execution environments](/guides/environments).
  </Accordion>

  <Accordion title="An environment type or network setting is rejected">
    On hosted Orca, `self_hosted` environments are coming soon, and `network.access: "restricted"` is not available. Use `openai_hosted` with `disabled` or `enabled` network access. Do not loosen the policy further than the task needs.
  </Accordion>

  <Accordion title="A self-hosted turn fails immediately">
    Only with an Orca server you run yourself. `workspace_directory` must be an absolute path with no symbolic links in it. On macOS `/tmp` is a symlink; use the real path.
  </Accordion>

  <Accordion title="A turn fails with usage_limit_exceeded and no param">
    "This plan's included machine hours for this period are used up": a Free plan has used its 3 hours of machine time. Upgrade to Pro or Max, or wait for the next month. See [plans](/plans#machine-time).
  </Accordion>
</AccordionGroup>

## Outputs

<AccordionGroup>
  <Accordion title="There is no artifact to download">
    * The agent must write the file under `/workspace/outputs` (or `outputs` in your self-hosted workspace).
    * Artifacts are captured only when a turn **completes**.
    * The agent saying it saved a file does not mean it did. Check the items for the command it ran.
    * Artifacts are deleted with their session.

    See [files and artifacts](/guides/files-and-artifacts).
  </Accordion>
</AccordionGroup>

## Reporting a problem

Include the client language and package version, the HTTP status and error `code`, a sanitized request body, the session and turn IDs, and whether it happens every time. Remove API keys, provider keys, vault contents, private prompts, and sensitive file content before sharing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.