Source: https://docs.cumuluslabs.io/troubleshooting
Content version: 38e68e0f

# 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 {#authentication}

| 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 {#refused-run}

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](/docs/runs#dynamic-variables). |
| Telephony validation diagnostic | Check the ready trunk, imported caller ID and secret references. See [Phone](/docs/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 {#conflicts}

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 {#unknown-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](/docs/api#errors).

## Webhook delivery {#webhooks}

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](/docs/triggers-and-webhooks#verify).

## Get useful help {#support}

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.