Orbitali Docs

Errors & Troubleshooting

Understand validation failures, activation conflicts, and failed conversations.

Check the HTTP status and response body before using a result. Public API failures normally include an error string, with optional code, details, or validation issues. Do not assume every error has a machine-readable code.

{
  "error": "Agent update conflict",
  "details": "Agent changed since expectedUpdatedAt; refetch and retry."
}

Resolve API failures

StatusLikely causeWhat to do
400Invalid UUID, missing field, invalid enum, or unsupported configurationRead issues[].path and issues[].message when provided. Required nullable fields still need null in full create requests.
401Missing, invalid, or revoked API keySend the full key in Authorization: Bearer …; verify the key belongs to the intended organization.
403 with FEATURE_NOT_AVAILABLERequested feature is unavailable on the account planRemove the unavailable setting or change the plan. For example, leave ambient sound as none.
404Resource absent or outside the key's organizationList resources using the same key and use the returned UUID. SIP also returns 404 when disabled.
409 with AGENT_LIMIT_EXCEEDEDActivation exceeds the active-agent allowanceCheck maxAgents, deactivate an unused agent, or change the plan. Drafts do not consume active-agent slots.
409 with Agent update conflictPATCH revision is staleGET the agent, review concurrent changes, and PATCH using its new agent.updatedAt.
409 for a realtime sessionAgent is not activeActivate it before requesting a public realtime session.
500 for a realtime sessionServer-side session configuration failedRetry later; if persistent, report the endpoint, time, status, and sanitized error.
502 for knowledge uploadKnowledge ingestion failedRetry later after checking document format and text content.

Endpoint-specific errors are listed with agents, phone numbers, MCP integrations, and SIP.

An agent exists but cannot take calls

Check its status with GET /public/v1/agents/{agent_id}. Creation always produces a draft. For phone calls, also check that the number is claimed, its carrier setup is complete, and it is assigned to this agent. For browser calls, request a fresh session and connect before expiresAt; do not reuse a cached URL.

A tool is missing or fails

  • Static agents do not accept custom HTTP/webhook tools. The agent type cannot be changed after creation.
  • HTTP tools require toolUrl. Verify HTTPS, endpoint credentials, method, parameters, and timeout. Private-network destinations are blocked by the runtime.
  • Webhook tools require a saved agent serverUrl. Dispatch message.toolCall.name and verify signatures against the raw request body.
  • Confirm the tool is enabled and its description tells the model when to invoke it. Registration does not guarantee every conversation will call it.
  • Review call detail and agent logs. Logs expose a rolling 24-hour window.

Retry without duplicating work

After a network timeout on a create or other write, first check whether it succeeded. Blind retries can create duplicate agents, tools, or external actions. For reads and transient service failures, retry with a bounded delay. For validation and authentication failures, correct the request first. For revision conflicts, refetch and reconcile rather than repeating the stale PATCH.

When sharing diagnostics, include the method, path, time, status, resource ID, and sanitized response. Remove API keys, webhook secrets, authentication headers, and caller data.

On this page