# Errors and limits

## MCP errors

Business failures are MCP tool results with `isError: true`, structured JSON, and a JSON text fallback. They keep HTTP 200 so MCP clients can surface actionable context.

| Code                     | Meaning                                                                                           | Next action                                                                                          |
| ------------------------ | ------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `NOT_FOUND`              | The resource is missing or outside the PAT organization.                                          | Refresh the relevant list; tenant boundaries are intentionally indistinguishable.                    |
| `REVISION_CONFLICT`      | `expectedRevision` is stale.                                                                      | Get the scenario or campaign again and reconcile.                                                    |
| `RESOURCE_LOCKED`        | Another editor currently holds the resource's temporary exclusive lease.                          | Wait for release or expiry, then read the latest revision before explicitly retrying the mutation.   |
| `SCENARIO_LOCKED`        | A linked campaign is active.                                                                      | Continue at the returned Studio URL.                                                                 |
| `CAMPAIGN_LOCKED`        | The campaign is not DRAFT or a routing change has open interactions.                              | Continue at the returned editor URL, or wait for open interactions before retrying a routing change. |
| `VALIDATION_FAILED`      | One or more semantic inputs are invalid.                                                          | Fix the structured issues and retry with a new intent/key if the body changes.                       |
| `QUOTA_EXCEEDED`         | Scenario, campaign, PAT, or webhook-endpoint capacity is full.                                    | Archive an unused resource in Studio, revoke/disable unused integration capacity, or upgrade.        |
| `IDEMPOTENCY_KEY_REUSED` | A key was reused with a different request.                                                        | Create a new key.                                                                                    |
| `TOOL_NOT_AVAILABLE`     | The PAT lacks the tool scope or the feature is disabled.                                          | Use an appropriately scoped PAT; do not guess hidden tools.                                          |
| `SERVICE_UNAVAILABLE`    | A required MCP dependency, including verified product-reference data, is temporarily unavailable. | Retry with bounded backoff; for knowledge search, do not substitute stale or cross-language content. |

HTTP `401`, `403`, `429`, and `503` are reserved for authentication, global entitlement, rate limiting, and infrastructure availability.

## Limits

- MCP request body: 256 KiB.
- MCP result body: 1 MiB.
- MCP request timeout: 15 seconds.
- PAT rate: 60 requests/minute/token.
- Organization MCP rate: 300 requests/minute.
- Active PATs: Growth 5; Scale 25 unless contract override.
- Active or pending webhook endpoints: Growth 5; Scale 25 unless contract override.
- Webhook payload: 256 KiB.
- Webhook request timeout: 10 seconds.
- Webhook replay: up to 30 days, bounded by source-data retention.

Limits protect the service and are not a monthly billable quota. Standard MCP product-reference search, authoring, lifecycle delivery, configuration, tests, no-match evaluations, failures, retries, and replay consume 0 Betterstood credits. A conditional automation consumes 1 activation credit only when delivery first succeeds.