Troubleshooting

Solutions to common problems. Before reporting a bug, check the response headers (x-livery-state, x-fallback-reason, x-image-source) — they explain what the API did.

Wrong / unexpected image

Symptom: livery shown is not the requested one

Likely cause: the requested livery doesn't exist for this plane × airline pair. The API falls back to the base livery, then to the blank image.

Diagnosis:

curl -I "https://api.aeromodel.dash-systems.fr/v1/images/plane?plane=airbus-a380-800&airline=emirates&liveryType=expo-2030" \
  -H "x-api-key: YOUR_KEY"

Look for headers:

x-livery-state: livery        # or "blank" / "fallback"
x-livery-status: ok           # or "fallback"
x-fallback-reason: livery-unavailable
x-livery-type: base           # actually applied livery

Fix: call /v1/catalog/liveries?plane=A380&airline=EK to list actually available liveries.

Symptom: aircraft doesn't look like the expected model

Likely cause:

• Variant unavailable → fallback to the family (e.g. airbus-a320-100 doesn't exist, we use airbus-a320-200).
• Wrong slug (typo, e.g. boing-737 instead of boeing-737).

Diagnosis:

curl "https://api.aeromodel.dash-systems.fr/v1/resolve?kind=plane&method=raw&value=B737-MAX" -H "x-api-key: YOUR_KEY"

Check the returned slug.

Symptom: weird colors / brightness

Likely cause:

• filetype=jpg on a blank aircraft with transparent background → JPG doesn't support transparency, the API uses white as default. Specify background=%23xxxxxx.
• Aggressive WebP compression on gradients.

Fix:

?filetype=png                          # lossless
?background=%23ffffff                  # explicit white background for JPG

Symptom: aircraft mis-positioned (too low, too high, off-frame)

Fix: add align=bottom. See align.

/v1/images/plane?plane=A320&airline=AF&angle=0&align=bottom

Symptom: watermark appears

Cause: no valid API key was passed.

Fix: send x-api-key header, or a Bearer token, or ?api-key= in the URL. See Authentication.

Aircraft not available / new aircraft to add

The API covers main commercial aircraft (Airbus, Boeing, Embraer, Bombardier, ATR, Sukhoi, COMAC, MHIRJ...). If a model is missing:

1. Verify it doesn't exist under another slug

curl "https://api.aeromodel.dash-systems.fr/v1/catalog/planes?query=787" -H "x-api-key: YOUR_KEY"

Search by:

• IATA code (787, 320, 380).
• ICAO code (B789, A20N).
• Part of the name (dreamliner, neo).

2. Check related variants

Many variants are not rendered separately (an A320-100 and an A320-200 share the image). Try the main family member:

• airbus-a320-100 → airbus-a320-200
• boeing-737-700 → boeing-737-800
• boeing-787-3 → boeing-787-8

3. Request an addition

If the aircraft is genuinely missing (e.g. a new 2026 model), open an issue on the repo with:

• Manufacturer + exact model.
• IATA and ICAO codes.
• Royalty-free reference image if possible.
• Priority airlines operating the aircraft.

The team adds new models in monthly batches.

Airline not found

Verify the slug

curl "https://api.aeromodel.dash-systems.fr/v1/catalog/airlines?query=airfrance" -H "x-api-key: YOUR_KEY"

If empty, try:

• IATA code (AF, EK, UA).
• ICAO code (AFR, UAE, UAL).
• Partial name (france, emirates).

Defunct airline

Bankrupt airlines remain available but are flagged defunct: true. The blank image is served automatically if no livery is in the database.

Request an addition

Issue on the repo with:

• Official + commercial name.
• IATA + ICAO codes.
• Country.
• If possible, current livery (link to official site).

API returns an error

See also

• Errors and fallbacks
• Response headers
• Terminology