> ## Documentation Index
> Fetch the complete documentation index at: https://docs.staging.cope-demo.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.                                                                                        |
| `insufficient_scope`          | 403    | The API key's permissions do not cover this operation.                                                                                            |
| `forbidden`                   | 403    | The API key is valid but is not permitted to perform this operation.                                                                              |
| `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.                                                                                    |
| `payload_too_large`           | 413    | The request body is larger than the API accepts. Do not retry the same body.                                                                      |
| `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.                                                                                                            |
| `internal_error`              | 500    | COPE could not complete the request because of an internal error. Retry with backoff, and quote `request_id` if it persists.                      |
| `impersonation_not_supported` | 501    | The public API does not accept impersonated requests. Send the request as the integration itself.                                                 |
| `upstream_error`              | 502    | The service behind this route could not be reached. Retry with backoff.                                                                           |
| `service_unavailable`         | 503    | COPE cannot serve the request temporarily. Retry with backoff.                                                                                    |
| `gateway_timeout`             | 504    | The request did not complete in time, and a write may still have been applied. Retry with backoff, sending the same `Idempotency-Key` on a write. |

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