Skip to main content

Errors

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

Envelope

Each entry of errors carries a snake_case machine code in code (for example blank, too_short, inclusion, or invalid when no more specific code applies) and a sentence for people in detail, and param names the field it is about when there is one. Branch on code; the wording of detail may change. When the problem lists errors, the top-level detail summarises them.

Common codes

Endpoint-specific codes are documented in each operation when they differ from the common catalog. A problem’s type is https://docs.cope.com/errors/ followed by its code.

Codes by operation

Codes that only some operations answer, with the status each is answered under.

Request IDs

Every response from the API carries an X-Request-Id header, and every error body repeats it as request_id. Send your own X-Request-Id (1 to 128 letters, digits, _, @ or -) to have COPE use it; otherwise COPE generates one. Quote it when you contact support. A replayed write, one answered from an earlier request with the same Idempotency-Key, carries Idempotent-Replayed: true.

Send a User-Agent

Send a User-Agent header on every request; any value that names your integration will do, such as my-shop-sync/1.4. COPE’s network edge may refuse a request without one before it reaches the API: the response is a 403 whose body is not application/problem+json and which carries no X-Request-Id. Most HTTP clients send a User-Agent by default; set one explicitly if yours does not.