CumulusDocs
Open Studio
On this page

Troubleshooting

Find the error's code and details.reason, then choose the matching section below. For example, invalid_request with missing_dynamic_variables means the request omitted values used by the published graph. Keep the request or run ID so you can find the same attempt in Studio or share it with support.

Authentication and permissions

SymptomCheckRecovery
401Key is present, active and valid for the endpointPass the intended tenant's bearer key to the selected Cumulus API or configured authenticated MCP gateway; public documentation retrieval needs none.
403Minimum role in the operation referenceUse the right role or ask an organization admin to perform the step.
Missing MCP toolsKey role and connectionConfirm the gateway upstream and tenant, then inspect the live tool inventory and role. A documentation-only connection cannot manage agents.
Resource missingCurrent environment, agent/run IDRead GET /api/v1/environments, then list the resource. Do not reuse IDs from another environment.

A run is refused

Read run capacity and the error reason. Cumulus configures run admission and capacity; workspace admins manage their own spending and daily-call caps.

Error or causeNext action
tenant_not_configuredAsk Cumulus to set capacity for the environment, supplying the slug and tenant ID from GET /api/v1/environments.
tenant_disabled or tenant_admission_closedAsk Cumulus to open admission for the current environment.
Missing required variablesInspect placeholders in the publication and pass their values as dynamic_variables. See Dynamic variables.
Telephony validation diagnosticCheck the ready trunk, imported caller ID and secret references. See Phone.
Budget or call limit refusalRead the limits and usage; an organization admin controls its own caps.
capacity_exhaustedWait for active runs to end, then retry with the same idempotency key. Contact Cumulus if you need a higher concurrent-run limit.

Simulations also need open run admission. Verify phone connectivity with a number you control; a test-marked phone run still dials it.

Draft or head conflict

A 409 means your draft revision or head changed. Read it again and compare the intervening change before sending a new edit or promotion. Never replace expected_revision with a guessed number or blindly overwrite another editor.

An SDK DraftConflict means the configuration changed since preview. Preview again and review the difference. A PartialApplyError means some changes may already be saved; inspect its receipt before continuing. If the intended change came from Studio, copy that change back to your TypeScript source before applying again. See Studio collaboration and recovery.

Inspect validation diagnostics by path. Apply the relevant typed edit against the current revision, then validate again.

Unknown command outcome

outcome_unknown means the response could not confirm whether the command completed. Retry with the same Idempotency-Key (MCP idempotency_key) and the same request. A new idempotency key can duplicate the work.

For a retryable read failure, wait briefly and retry a limited number of times. For a refusal such as a missing variable or denied permission, fix the cause before sending the request again. See API errors.

Missing outputs or silent audio

A WaitTimeout means your application stopped waiting, not that the call stopped. Retain its run ID and read it again. For missing outputs, check transcript, recording and analysis states independently; they can finish after the run. For a silent call, check the selected agent version, speech profile, caller context and carrier path, then listen to the available recording.

For a customer tool failure, check endpoint authentication, exact raw body handling, schema, call.run_id, the distinct conversation call.call_id, and durable effect deduplication. A phone-number lookup is not verification of the human caller. Keep private values and secret-bearing requests out of diagnostic logs.

Webhook delivery

Verify the signature over the original request body with the configured signing secret, and deduplicate the event identity. Do not parse and reserialize JSON before verifying. Test runs are excluded from notifications and triggers. See Webhook delivery and verification.

Contact support

Send your Cumulus contact the operation, error code and reason, environment slug, resource IDs and approximate time. Include a request or run ID when available. Redact API keys, SIP passwords, signing secrets and caller content before sharing logs.

Content version dc5ad943Customer SDKMarkdown source
Troubleshooting · Cumulus developer docs