Errors and fallbacks

The API distinguishes two failure families:

1. HTTP errors (4xx / 5xx) — request rejected, JSON payload.
2. Image fallbacks (200 OK) — request succeeds but the served image is not exactly the one requested. Diagnostic headers are returned.

HTTP errors

400 Bad Request

Invalid parameter. Payload:

{
  "error": "invalid render options",
  "details": ["zoomLevel must be a number between 0.5 and 3"]
}

Typical causes:

401 Unauthorized

Protected endpoint without a valid key (except /v1/images/plane which degrades).

{ "error": "unauthorized" }

See Authentication.

404 Not Found

• Unknown route: { "error": "not found" }
• In format=json mode, unresolved aircraft: { "error": "plane not found", "requested": "..." }
• Asset missing from storage: { "error": "asset missing in storage", "assetKey": "..." } — rare, indicates a manifest/R2 inconsistency.

405 Method Not Allowed

All routes are GET-only. Any other verb → 405.

5xx

Unexpected error on Worker or R2 side. Cloudflare retries automatically. If it persists, contact the maintainer.

Image fallbacks (200 OK)

On /v1/images/plane, as long as the aircraft is resolved and parameters are valid, an image is always served. The cascade:

Sample fallback response:

HTTP/1.1 200 OK
Content-Type: image/png
x-livery-state: blank
x-livery-status: fallback-blank
x-livery-type: blank
x-fallback-reason: airline-not-found
x-image-source: r2-blank

What to do client-side

• Display the image anyway: it's a real, usable image.
• Log x-fallback-reason to detect missing combinations to report.
• Use format=json mode if you want to decide client-side NOT to display when a fallback occurred. The JSON payload lists the resolution state without serving an image.

Unauthorized watermark

If a request reaches /v1/images/plane without a valid key, the API serves the normal image with a watermark overlay. Headers:

x-auth-status: unauthorized
x-image-source: watermark-overlay

This allows public integrations to work in demo mode.

Reporting missing combinations

When a fallback is applied (steps 2-4), the Worker writes a JSON flag in R2 in the background (missing/...) so the maintainer can identify liveries to pre-generate first. No client action required.