> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cope.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors

> COPE public API errors use RFC 9457 application/problem+json envelopes with stable codes.

# Errors

COPE public API errors use RFC 9457 `application/problem+json`. The `code` field is stable and should drive client behavior.

## Envelope

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "code": "validation_failed",
  "detail": "Request validation failed",
  "errors": [
    {
      "code": "missing",
      "detail": "Name is required",
      "param": "name"
    }
  ],
  "request_id": "req_...",
  "status": 422,
  "title": "Validation Failed",
  "type": "https://docs.cope.com/errors/validation_failed"
}
```

## Common codes

| Code                    | Status | Meaning                                                                               |
| ----------------------- | ------ | ------------------------------------------------------------------------------------- |
| `missing_authorization` | 401    | The `Authorization` header is missing or is not a Bearer token.                       |
| `invalid_token_format`  | 401    | The Bearer value is neither a COPE secret key nor a supported Clerk bearer token.     |
| `invalid_token`         | 401    | The credential is invalid, revoked, inactive, or uses an unsupported mode.            |
| `business_required`     | 401    | Clerk authentication requires `X-Cope-Business-Id`.                                   |
| `business_forbidden`    | 403    | The Clerk user does not belong to the requested business.                             |
| `auth_method_forbidden` | 403    | The operation does not allow the supplied credential type.                            |
| `unknown_version`       | 404    | The requested API major version is not supported.                                     |
| `unknown_public_route`  | 404    | The route is not released in the public API.                                          |
| `not_found`             | 404    | The requested resource was not found or is not visible to the authenticated business. |
| `invalid_request`       | 400    | The request shape is malformed or includes unsupported fields.                        |
| `invalid_parameter`     | 422    | A query or body parameter has an invalid value.                                       |
| `validation_failed`     | 422    | One or more fields failed validation. Inspect `errors[]`.                             |
| `invalid_state`         | 422    | The requested command is not valid for the resource state.                            |
| `rate_limited`          | 429    | Too many requests. Retry with backoff.                                                |
| `service_unavailable`   | 503    | COPE cannot serve the request temporarily. Retry with backoff.                        |

Endpoint-specific codes are documented in each operation when they differ from the common catalog.