API errors, caching, and compatibility
Handle delivery API status codes and problem responses, validate cached pages safely, and keep API, schema, and publication versions separate.
Check the HTTP status first
Successful page lookups return application/json. Errors use application/problem+json, with the HTTP status repeated in the body for convenience. The transport status is authoritative.
| HTTP status | Stable code | Recommended handling |
|---|---|---|
| 400 | INVALID_QUERY | Fix missing, repeated, invalid, or unsupported parameters |
| 403 | ACCESS_DENIED | Stop the request; do not substitute another website |
| 404 | PAGE_NOT_FOUND | Show a real not-found result; do not expose unpublished content |
| 422 | UNSUPPORTED_PAGE_KIND | Use the existing content-list interface for collection entrypoints; do not retry as an outage |
| 429 | RATE_LIMIT_EXCEEDED | Back off; respect Retry-After when provided |
| 500 | INVALID_DELIVERY_RESOURCE | Report a representation failure; do not render a partial payload |
| 503 | DELIVERY_UNAVAILABLE | Treat the service as temporarily unavailable; use bounded retries |
A typical missing-page error is:
{
"type": "about:blank",
"title": "Not Found",
"status": 404,
"detail": "Published page not found.",
"code": "PAGE_NOT_FOUND",
"requestId": "example-request-id"
}
Use code for program decisions and requestId when reporting a problem. Do not parse English detail text to classify errors. Error responses use Cache-Control: no-store and do not include database diagnostics, draft text, or a successful replacement page.
Validate a cached representation
A successful page response includes a weak ETag and Cache-Control: public, no-cache. Here no-cache permits storage but requires revalidation before reuse; it does not mean the same thing as no-store.
Send the exact ETag back in If-None-Match. If the currently published representation still matches, the API returns HTTP 304 with no response body. Reuse your previously stored representation rather than attempting to parse JSON from a 304.
GET /api/delivery/v1/pages/by-path?domain=your-site.lit.page&path=/pricing
If-None-Match: W/"replace-with-the-etag-from-your-previous-response"
Key a cached page by its complete lookup, including hostname, path, and language. A cache for one website or language must never satisfy another lookup.
Know what changes the validator
The ETag covers the complete selected response. Publishing new page content, updating public navigation, changing a footer, or changing returned SEO metadata can produce a new ETag. Editing an unpublished draft does not change the published page response.
Publication is checked before a 304 is returned. If a page is withdrawn, a previously valid ETag does not keep it publicly readable: the lookup returns a not-found result. Authorized previews remain separate and must not be placed in a public content cache.
Keep integrations compatible
Delivery v1 uses a resource representation rather than the legacy success/data envelope. Existing /api/v1/render interfaces remain available during migration. A consumer that explicitly selects delivery v1 should reject an unexpected legacy response instead of silently guessing its meaning.
Consumers should validate required fields and supported schema versions while tolerating documented additive fields. Do not depend on property ordering, hidden management fields, or internal database layout. A new content revision is not an API upgrade.
For the available operations and exact schemas, use /api/delivery/v1/openapi.json on the same API deployment you call. Return to API overview for the boundaries between delivery, management, and preview.