---
title: "Errors"
description: "Stable Cadence error codes, HTTP admission failures, tool errors, and retry guidance."
canonical_url: https://cadence-me.com/developers/errors
last_updated: 2026-10-18
status: stable
source: src/data/developers.ts
---

# Errors

## Reading a failure

Admission errors use HTTP status codes: invalid tokens return 401, missing scope 403, and exhausted grant limits 429 with Retry-After. Authentication challenges identify the protected resource or missing scope. OAuth uses its own protocol errors, such as invalid_grant and access_denied.

Tool failures carry isError=true and a structured Cadence error. The catalog's HTTP status describes the error mapping; a completed MCP tools/call exchange can carry a tool error inside an HTTP 200 response. Do not treat HTTP 200 alone as a successful edit.

## Error catalog

| Code | HTTP status | Retryable | Before retrying | Meaning |
|---|---|---|---|---|
| `invalid_input` | 400 | yes | `after_change` | The input does not match the tool's schema or rules. `field_errors` names each problem. |
| `limit_exceeded` | 400 | yes | `after_change` | The request asks for more than a contract limit allows, such as too long a date range or too large a result. Narrow the request. |
| `not_found` | 404 | no | `never` | No record with that id exists for this account. |
| `conflict` | 409 | yes | `after_refresh` | The record changed since it was read: `expected_status` or `expected_revision` is stale. Nothing changed. |
| `idempotency_key_reused` | 409 | yes | `after_change` | The `idempotency_key` was already used with a different input. Use a new key for a new request. |
| `invalid_state` | 409 | yes | `after_refresh` | The record's current state does not allow this change. |
| `authentication_required` | 401 | yes | `after_authorization` | The access token is missing, expired, revoked, or issued for another resource. Reconnect Cadence. |
| `insufficient_scope` | 403 | yes | `after_authorization` | The connection does not include the permission this tool needs. `required_scopes` lists it. |
| `rate_limited` | 429 | yes | `after_delay` | Too many requests for this connection. Retry after `retry_after_seconds`. |
| `service_unavailable` | 503 | yes | `after_delay` | Cadence integrations are temporarily unavailable. |
| `internal_error` | 500 | yes | `after_delay` | Cadence could not complete the request. Nothing is assumed to have changed; retry once with the same `idempotency_key`. |

## Retrying safely

Read retry and retry_after_seconds. The retryable flag does not mean retry immediately. After conflict, reread the record and ask whether the intended edit still applies. Retry an uncertain write with the same idempotency_key and unchanged arguments. See [idempotency and concurrency](/developers/idempotency).

Never include tokens or returned note text in error reports. Inspector 2.11.0 has a known display issue with error structuredContent; see [troubleshooting](/developers/troubleshooting).
