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

​
Setup

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 (pip show openai or npm ls openai shows what is installed) and restart long-running processes.
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.
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.
Check that the URL is https://api.orcapods.ai/v1, spelled exactly, with https://.
“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.
“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. “Rate limit reached. Retry after N seconds.” means too many requests in a minute; wait that long, as the Retry-After header says.
“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, or use a model on your own key in a session without a sandbox.

​
Models

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 to a model on the other side with POST /api/sessions/{session_id}/model. See models and provider keys.
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.
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.
A turn is running, or waiting for your function results. Switch once it ends.
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.

​
Turns

Sending returns before the agent answers. Wait for the turn to end first. See turns and statuses.
Check sessions.retrieve(session_id):
  • requires_action with a function_call: your application has to send the tool result. See 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.
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.
idle only means no turn is running. Check the newest turn’s status and error.
The turn keeps running. Read its status, then reconnect if needed. See streaming.

​
Tools and environments

“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 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.
The session has environment: {"type": "none"}. Create a new session with a sandbox. See execution environments.
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.
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.
“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.

​
Outputs

  • 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.

​
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.