Errors

The error envelope

Every error response is a JSON object with a machine-readable error code and, in most cases, a human-readable error_description:

{
  "error": "bad_request",
  "error_description": "offset too deep: offset + limit must not exceed 10000 (the OpenSearch result window)."
}

error_description is informational and may change; branch on the HTTP status and the error code, not on the description text.

Status codes

Status	error code	When
400	bad_request	Malformed request — missing path id, a deep offset past the result window, an invalid expires_at, a missing segment name/condition, a cursor that is malformed or bound to a different profile/endpoint, or (on ingest) a non-JSON or non-object body.
401	unauthorized	No or invalid credential.
403	forbidden	Authenticated but not allowed — no connected shop resolves a scope; a non-staff caller targeting another brand; an API key used for key management; a cursor minted for a different brand; or (on ingest) a disallowed Origin or a payload scope that does not match the requesting storefront.
404	not_found	Profile not found or out of scope (indistinguishable by design, so a brand cannot probe another brand’s ids).
405	method_not_allowed	Unsupported method for the route (e.g. a non-GET on a read endpoint, or an unrecognized method on /cdp/keys or /cdp/segments).
413	payload_too_large	Ingest request body exceeds the 64 KB cap.
502	upstream_error / bad_gateway	The CDP backend could not persist a segment or the ingest target failed/was unconfigured.
500	internal_error	Brand-scope resolution failed unexpectedly.

Notes

• A 404 from a single-profile read does not tell you whether the id exists for another brand — out-of-scope and not-found are deliberately the same response.
• The credential-free ingest path uses the same envelope but a narrower set of codes (400, 403, 405, 413, 502, plus whatever status the upstream returns on success/failure).