Error handling

Every error is an RFC 7807 problem document with content type application/problem+json. Errors are not wrapped in the data/meta envelope.

{
  "type": "urn:qup:error:checkout-reservation-expired",
  "title": "reservation has expired",
  "status": 404,
  "detail": "the reservation has expired, please place a new one",
  "instance": "urn:qup:correlation:0f4c8e1a-9b2d-4c7e-8a1f-2d3b4c5e6f70"
}

When type is absent

type and detail accompany a named failure — one the platform can describe safely. Two
kinds of response arrive without them:

1. Unexpected server faults. A 500 carrying only a title means the cause was not something we
   can put in a response body. Quote the instance correlation id and we can trace it.
2. Orders and tickets. The fulfillment routes answer with
   status, title and instance. Branch on the HTTP status there, and on type elsewhere.

Raw infrastructure errors are never echoed back, so a missing detail means the underlying cause
was not safe to share rather than that the response is incomplete. The correlation id is the way
in.

Status codes and what they mean here

404 hides ownership on purpose

Where a resource belongs to a specific customer — a fulfillment order, a checkout bound to a signed-in user — asking for someone else's returns 404, not 403. The two cases are indistinguishable by design, so order ids cannot be enumerated across users. Do not read a 404 as proof the id is wrong.

The exception is guest checkouts: a checkout created without a session has no owner, so the checkout_id itself is the capability. Anyone holding it can read it. Treat a guest checkout_id as a secret.

502 needs thought, not blind retries

A 502 means we reached a third party and it failed. Whether a retry is safe depends on the endpoint: on a read it always is; on confirm checkout the safe retry is the same request with the same Idempotency-Key, which either replays the original result or re-attempts cleanly. Never re-issue a confirm with a fresh key after a 502 — that is how you double-charge someone.

Retry policy

Retry only 429, 500, 502, 503 and 504. Use truncated exponential backoff with full jitter:

delay = min(30s, 1s * 2^attempt) * random(0, 1)

Stop after 5 attempts and surface the failure. When a Retry-After header is present, honour it and ignore the formula for that interval — it is a real signal, not a guess. For anything carrying an Idempotency-Key, retry with the same key; see Idempotency.

Slug catalogue

Every type a retailer-facing endpoint can return, grouped by area. The slug is the part after urn:qup:error:.

Checkout

Sessions and authentication

Catalog

Vouchers

Loyalty wallet and memberships

Agreements

Payments and analytics

What to log

For every failed call, record: the endpoint, the HTTP status, type, and instance. That is enough for us to resolve almost anything without a round trip. Never log the request body of a checkout confirm — it contains customer name, e-mail and address.