Error envelope

Every error response — on every surface, from validation failures to authorization rejections to server errors — uses the same JSON shape. Write one error handler and it works against the whole API.

{
  "code": "string",
  "message": "human-readable summary",
  "details": {}
}

• code — an open-ended, machine-readable identifier. Known codes are stable and safe to branch on, but the catalog is not exhaustive.
• message — a human-readable summary, safe to log; not intended for end-user display verbatim.
• details — optional structured context (e.g. per-field validation errors). Present when there's more to say.

This envelope is documented in OpenAPI as a shared schema and referenced by every endpoint's 4xx/5xx responses, so it shows up consistently in the API reference.

Handling new codes

Branch on a known code when you need a specific recovery path. Always keep a fallback for an unknown code: use the HTTP status and the generic envelope to choose the default behavior, and treat message as informational rather than parsing it.

litecommerce may add a code without a deprecation window when it keeps the documented HTTP status and envelope semantics. A known code's spelling and meaning remain stable; removing, renaming, reusing, or incompatibly changing one follows the breaking-change lifecycle.

Common status codes

The downloadable OpenAPI document publishes the stable known-code catalog in components.schemas.ApiErrorDto.properties.code.x-extensible-enum. Generate clients so they accept an unknown string in addition to the listed values.