Errors

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

Envelope

{
  "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.

​Errors

​Envelope

​Common codes

Errors

Envelope

Common codes