Errors & conventions

These conventions hold across both the Store and Creator APIs.

Transport

• HTTPS only. All traffic goes through the shared API gateway on the api.* domain (see Environments).
• JSON in, JSON out. Send Content-Type: application/json on requests with a body; responses are application/json.
• Bearer auth. Send credentials as Authorization: Bearer <token>. See Authentication.

Identifiers

• Store API resources use prefixed string IDs — e.g. prod_… for products and ord_… for orders — so an ID is self-describing.
• Creator API resources are identified by UUIDs.

Treat all IDs as opaque strings; don’t parse or construct them.

Money

Monetary amounts are integer minor units of the currency — pennies, cents, etc. 1099 in a GBP context means £10.99. Never assume two decimal places; read the accompanying currency code.

Timestamps

Timestamps are ISO 8601 / RFC 3339 strings in UTC, e.g. 2026-07-20T10:32:00.000Z.

Pagination

List endpoints are paginated and return a data array alongside a meta block:

{
  "data": [{ "...": "..." }],
  "meta": { "page": 1, "per_page": 25, "total": 137 }
}

Request the next page with the endpoint’s page / per_page query parameters (see each operation in the reference for its exact bounds).

Errors

All errors share a single flat envelope:

{
  "statusCode": 404,
  "code": "NOT_FOUND",
  "error": "Not Found",
  "message": "Release prod_123 was not found."
}

• statusCode — the HTTP status, repeated in the body.
• code — a stable, machine-readable enum (below). Branch on this, not on message.
• error — the HTTP status text.
• message — a human-readable description; may change, don’t parse it.

Error codes

HTTP	code	When
400	VALIDATION_ERROR	The request failed schema validation.
401	UNAUTHORIZED	Missing, malformed, or expired credentials.
403	FORBIDDEN	Authenticated, but not permitted / missing a scope.
404	NOT_FOUND	The resource does not exist (or isn’t visible to you).
409	CONFLICT	The request conflicts with current state.
422	UNPROCESSABLE_ENTITY	Well-formed but semantically invalid.
429	RATE_LIMITED	Too many requests — see Rate limits.
503	SERVICE_UNAVAILABLE	The service is temporarily unavailable / not ready.
500	INTERNAL_ERROR	An unexpected server error.

Retry 429 and 503 with backoff (they’re transient); do not blindly retry 4xx — fix the request first.

Health

Each service exposes unauthenticated probes: GET /health/live (liveness) and GET /health/ready (readiness). ready returns 503 while the service is starting up or a dependency is unavailable.