The API adds several diagnostic headers to every /v1/images/plane response. They are safe to inspect client-side (CORS) and useful for debugging + monitoring.
Image diagnostics
| Header | Description | Example |
|---|
x-image-source | Origin of the served image | r2-livery, r2-base, r2-blank, r2-default, composed, watermark-overlay |
x-livery-state | Livery resolution state | livery, blank, fallback |
x-livery-status | Detailed status | ok, fallback-base, fallback-blank, composed-pitch, etc. |
x-livery-type | Applied livery type (may differ from requested liveryType) | base, retro, special-pride |
x-effective-gear | Actually used gear (if gear=up unavailable, falls back to down) | down, up |
x-fallback-reason | Present only on fallback | livery-unavailable, airline-not-found, blank-missing, gear-up-unavailable-used-down |
x-auth-status | Present only on unauthenticated requests | unauthorized |
x-manifest-version | Manifest version that served the asset | 2026-04-29T18:03:11Z |
Render diagnostics
| Header | Description |
|---|
x-render-width | Final width in pixels |
x-render-zoom-type | contain or fill |
x-render-zoom-level | Applied zoom multiplier |
x-render-margin-percent | Margin as % of canvas width |
x-composition-mode | storage-prebuilt, storage-fallback, composed-runtime |
Composition diagnostics (when pitch, scale, align, background parameters are used)
| Header | Description |
|---|
x-compose-pitch | Number in degrees (e.g. 20, -15) |
x-compose-align | top, center, bottom |
x-compose-scale | none, fleet, absolute |
x-compose-reference-plane | Reference plane slug (in fleet mode) |
x-compose-background | none, solid:#hex, gradient:linear |
| Header | Description |
|---|
x-format-requested | Filetype originally requested in the URL (png, jpg, webp) |
x-format-coerced | Present only when the actual returned format differs from the request — currently always png (composition forces PNG) |
Cache (Cloudflare)
| Header | Description |
|---|
cf-cache-status | HIT, MISS, REVALIDATED, BYPASS, STALE |
age | Seconds since cached |
cache-control | public, max-age=86400 |
etag | Asset hash, for conditional requests |
Standards
| Header | Description |
|---|
content-type | image/png, image/jpeg, image/webp, or application/json |
content-length | Size in bytes |
vary | Accept-Encoding |
Full example
HTTP/1.1 200 OK
content-type: image/png
content-length: 184523
cache-control: public, max-age=86400
cf-cache-status: HIT
age: 1247
etag: "9f3a..."
x-image-source: r2-livery
x-livery-state: livery
x-livery-status: ok
x-livery-type: base
x-effective-gear: down
x-manifest-version: 2026-04-29T18:03:11Z
x-render-width: 1024
x-render-zoom-type: contain
x-render-zoom-level: 1
x-render-margin-percent: 8
x-composition-mode: storage-prebuilt
