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.
`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.