> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.kuudo.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.kuudo.com/_mcp/server.

# Errors and limits

> Interpret authorization failures, asynchronous conflicts, and throttling.

## Errors

Error envelopes vary by endpoint. Organization authorization failures can use a
string `error` with a top-level `code`:

```json
{
  "error": "Insufficient scope",
  "code": "insufficient_scope",
  "requiredScopes": ["servers:read"]
}
```

Shared route errors can use a nested object:

```json
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing or invalid Authorization header"
  }
}
```

Storage errors can also include `errorCode`, `message`, and `remediation`.
Use the HTTP status first, then the documented endpoint-specific code.

| Status | Interpretation                                                         |
| ------ | ---------------------------------------------------------------------- |
| 400    | Invalid input or an unsupported operation/resource state               |
| 401    | Missing/invalid credentials or an inactive machine principal           |
| 403    | Missing scope, entitlement, or provider authorization                  |
| 404    | Missing resource or a resource hidden from the caller                  |
| 409    | State conflict, duplicate resource, or incompatible idempotency replay |
| 422    | Provider or organization prerequisite/availability failure             |
| 429    | Throttled; honor `Retry-After` when supplied                           |
| 500    | Internal error                                                         |
| 503    | Dependency unavailable or application maintenance                      |

## Rate limits

| Operation                                  | Limit      | Identity                                             |
| ------------------------------------------ | ---------- | ---------------------------------------------------- |
| Token exchange                             | 60/minute  | Trusted client IP and valid API key, independently   |
| API-key introspection                      | 120/minute | Trusted client IP and matched API key, independently |
| Invitation creation (development contract) | 20/minute  | Organization and actor                               |

Throttled responses include `Retry-After`. Some auth responses also expose
`X-RateLimit-Remaining` and `X-RateLimit-Reset`. There is no single universal
request quota across this reference.

## Retry behavior

Cache and reuse an unexpired exchanged JWT to avoid unnecessary exchange calls.
Retry read requests after transient failures with bounded backoff. Before
retrying a mutation, inspect its resource and jobs; most infrastructure endpoints
do not provide an idempotency-key contract.

Invitation creation requires `Idempotency-Key`. Reuse that key only with the same
body. A changed body returns a conflict, and terminal replay omits the capability URL.

During application maintenance, affected API requests return `503` with
`code: "MAINTENANCE_MODE"`, `Retry-After: 60`, and `Cache-Control: no-store`.