On this page
Troubleshooting
Use the API error code and details.reason to find the next action. Read your environment and resource state before changing configuration.
Authentication and permissions
| Symptom | Check | Recovery |
|---|---|---|
| 401 | Key is present, active and valid for the endpoint | Pass a bearer key for /mcp or API requests; public /mcp/docs needs none. |
| 403 | Minimum role in the operation reference | Use the right role or ask an organization admin to perform the step. |
| Missing MCP tools | Key role and connection | tools/list only shows operations the live role permits. |
| Resource missing | Current environment, agent/run ID | Read environments_list, then list the resource. Do not reuse IDs from another environment. |
A run is refused
Start with runs_capacity and the structured error. Ask Cumulus to configure staff-owned admission/capacity; a customer admin cannot do that through tenant operations.
| Error or cause | Next action |
|---|---|
tenant_not_configured | Ask Cumulus to set capacity for the environment, supplying the slug and tenant ID from environments_list. |
tenant_disabled or tenant_admission_closed | Ask Cumulus to open admission for the current environment. |
| Missing required variables | Inspect placeholders in the publication and pass their values as dynamic_variables. See Dynamic variables. |
| Telephony validation diagnostic | Check the ready trunk, imported caller ID and secret references. See Phone. |
| Budget or call limit refusal | Read the limits and usage; an organization admin controls its own caps. |
A simulation still needs admission. A real phone test still dials the destination. Do not use real calls as a connectivity probe.
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.
Inspect validation diagnostics by path. Mechanical fixes include typed edits; review the described behavior change, apply it against the validated revision, and validate again.
Unknown command outcome
outcome_unknown means the acknowledgement was lost; it does not mean the command failed. Retry with the same Idempotency-Key (MCP idempotency_key) and the same request. Starting a new logical attempt can duplicate work.
For ordinary retryable read failures, retry with bounded backoff. For a deterministic refusal, fix its cause first. See API errors.
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.
Get useful help
Give your Cumulus contact the operation, error code/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.