Errors¶

Every failing request on the HTTP API answers application/json in the same shape, with one exception: POST /api/v1/restore answers with its own result shape - see Restore result. Error codes lists every code the API returns.

The error body¶

{
  "error": {
    "code": "validationFailed",
    "message": "out of range",
    "field": "brightness"
  }
}

Restore result¶

POST /api/v1/restore does not use the shape above. Every response to it - success or failure - is this result object instead:

{
  "ok": true,
  "applied": {
    "wifi": 1, "system": 1, "settings": 1, "appLoop": 3, "radioStations": 0,
    "icons": 2, "melodies": 0, "palettes": 1, "scripts": 0, "skipped": 0
  },
  "warnings": []
}

The status is 200 when ok is true and 400 when it is false.

One case answers in the standard error body instead: if the upload finishes without ever receiving a backup file, the response is 400 with {"error":{"code":"badRequest","message":"no backup file received"}} - there is nothing to report counts for.

Error codes¶

field appears on five codes only, so do not write clients that require it. invalidName always carries field: "name". payloadTooLarge and insufficientStorage carry it on the script routes, and serviceBusy carries "name" (script install) or "url" (radio play). validationFailed carries it for every rejected value, but not when a route rejects a missing body - there is no offending key to name.

The values behind payloadTooLarge and insufficientStorage - how large a body may be, how many apps, notifications and scripts fit - are collected in Limits.

Status codes¶

A 507 on a full store or queue reads storage capacity reached; a script install past scriptLimit says script limit reached (N installed) and carries field: "name" instead.

device/reboot, device/sleep, device/factory-reset and settings/reset write their 200 {"ok":true} before the restart or deep-sleep is triggered, so the response is delivered normally.

404 messages¶

curl -i -X PUT http://<awtrix-ip>/api/v1/apps/active \
  -H 'Content-Type: application/json' \
  -d '{"name":"NoSuchApp"}'
# HTTP/1.1 404 Not Found
# {"error":{"code":"notFound","message":"app not found"}}

Method not allowed¶

The message is always allowed method(s): <list>. Every route below is matched by the router, so a wrong method on any of them answers 405. Only a genuinely unrecognized path falls through to 404 notFound with unknown route.

curl -i -X GET http://<awtrix-ip>/api/v1/notifications
# HTTP/1.1 405 Method Not Allowed
# {"error":{"code":"methodNotAllowed","message":"allowed method(s): POST"}}

App names are checked before the method¶

On /api/v1/apps/{name} the name is validated first, so a path that names nothing valid answers 400 invalidName rather than 405. That is what a bare sub-collection path hits: the tail of /api/v1/apps/script/ is script/, which is not an app name.

curl -i -X GET http://<awtrix-ip>/api/v1/apps/script/
# HTTP/1.1 400 Bad Request
# {"error":{"code":"invalidName","message":"name must match [A-Za-z0-9_-]{1,32}","field":"name"}}

active, next, previous and order are matched before the by-name route, so they keep their own allowlists: DELETE /api/v1/apps/next is 405 allowed method(s): POST, not the deletion of an app called next.

Authentication (401)¶

Auth is off by default. It turns on only when authEnabled is set (PUT /api/v1/system), which in turn requires a non-empty authUser and authPass - a username on its own changes nothing. Once on, it applies in every mode, including AP/provisioning - there is no blanket bypass. During provisioning AWTRIX also answers far fewer routes - reads, Wi-Fi setup and a reboot (see Provisioning lockdown), so a bystander in range still cannot drive the write API even before you set a password.

When it is on, AWTRIX speaks standard HTTP Basic:

HTTP/1.1 401 Unauthorized
WWW-Authenticate: Basic realm="AWTRIX NG"
Content-Type: application/json

{"error":{"code":"unauthorized","message":"authentication required"}}

• The WWW-Authenticate header is what makes a browser show its login prompt.
• The body is JSON in the standard error shape, not HTML - so a client can parse every status the same way.
• Auth guards everything AWTRIX serves, including GET / (the web UI) and the static /ICONS/, /MELODIES/ and /PALETTES/ assets.
• The two upload routes (POST /update, POST /api/v1/files) check credentials inside their upload handler and answer the same 401.

curl -u admin:secret http://<awtrix-ip>/api/v1/device

Provisioning lockdown (403)¶

While AWTRIX is in AP / provisioning mode most of the HTTP API is closed off. Only reads, the Wi-Fi write (PUT /api/v1/system) and POST /api/v1/device/reboot are reachable; the rest of the write API, the multipart file upload (POST /api/v1/files) and the firmware upload (POST /update) answer:

HTTP/1.1 403 Forbidden
Content-Type: application/json

{"error":{"code":"forbidden","message":"not available during provisioning"}}

The upload routes carry their own messages - file upload is disabled during provisioning and firmware update is disabled during provisioning. The soft-AP itself is still open (no Wi-Fi password), but very little is reachable and, if you have configured an authUser, still authenticated.

Content-Type: the empty-body trap¶

On PUT and PATCH, a body is rejected only when the request carries a Content-Type header whose value is not application/json - the header itself is not required. The one exemption: PUT /api/v1/apps/script/{name} carries Berry source rather than JSON, so it accepts any content type - see installing a script.

The trap is curl -d, which sends Content-Type: application/x-www-form-urlencoded by default rather than omitting the header - and that is what gets rejected:

• A body whose Content-Type is present and is not application/json returns 415 unsupportedMediaType (Content-Type must be application/json) - before the body is even parsed. This is where a curl -d without an explicit -H lands.
• A request that omits the Content-Type header altogether is not rejected by this check; the body is read and parsed as JSON normally.
• An empty or {} body on a route that requires one returns 422 validationFailed with a message naming what to send instead.

On the other routes an empty body and a literal {} part ways: a zero-byte body is never valid JSON, while {} is a well-formed object with nothing in it.

Deleting an app, turning the mood light off, or clearing an indicator is done only through the explicit DELETE route (or, over MQTT, the empty-payload clear idiom). An empty body is never destructive.

Always send the header explicitly:

# WRONG - curl sends application/x-www-form-urlencoded; on a PUT/PATCH this
# returns 415 unsupportedMediaType:
curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/hello -d '{"text":"hi"}'

# RIGHT
curl -X PUT http://<awtrix-ip>/api/v1/apps/pushed/hello \
  -H 'Content-Type: application/json' \
  -d '{"text":"hi"}'

Validation messages¶

A rejected value names the offending key in field. These are the messages AWTRIX produces.

PATCH /api/v1/settings¶

Every key in the payload is checked before anything is applied; the first offender is reported.

curl -i -X PATCH http://<awtrix-ip>/api/v1/settings \
  -H 'Content-Type: application/json' \
  -d '{"brightness":999}'
# HTTP/1.1 422 Unprocessable Entity
# {"error":{"code":"validationFailed","message":"out of range","field":"brightness"}}

Other routes¶

Two routes skip some validation. PUT /api/v1/display/moodlight rejects an empty or {} body with 422 (above); a bad brightness or kelvin value is silently truncated rather than rejected, but an unparseable color is rejected with 422 validationFailed and field: "color" - the same treatment PUT /api/v1/indicators/{id} gives it. PUT /api/v1/apps/active uses the body as a literal app name, so a malformed body answers 404 app not found rather than 400.

Per-app effect and overlay names¶

A pushed app or notification whose effect or overlay is not in the registries is rejected with 422 validationFailed and field: "effect" / field: "overlay", and nothing is stored - an array payload is all-or-nothing, so one bad element rejects the whole batch. The accepted names come from GET /api/v1/capabilities. This is the same treatment the global overlay on PATCH /api/v1/display has.

Boot replay is more tolerant: a stored app that fails this check is skipped at boot rather than rejected, so the rest of your rotation still comes up.

PUT /api/v1/system¶

Every numeric field is range- and type-checked before anything is stored, so a rejected request changes nothing and field names the offending key:

A value of the wrong type answers must be an integer (or must be a number on the five decimal fields); a value of the right type outside the range answers out of range. panelStart and panelWiring answer must be one of: <names>, and panelSerpentine, mirror and rotate answer must be a boolean.

Three cross-field rules are checked on the merged configuration, so a partial body that sets only one half of a pair is caught too:

The five static-address fields - ip, gateway, subnet, dns1, dns2 - must be a dotted quad or the empty string. ip may also carry the mask as a CIDR suffix (192.168.1.50/24), which is stored as the separate ip and subnet values.

Anything else answers must be an IPv4 address like 192.168.1.50, or "" to leave it unset; on ip the message reads must be an IPv4 address like 192.168.1.50 or 192.168.1.50/24, or "" to leave it unset. Sending both a /prefix on ip and a non-empty subnet in one request answers 422 on subnet: the /prefix on "ip" already names the mask; send one or the other.

Two subsystems are gated by their own switch, and each gate is refused unless the fields it needs are present. Blanking wifiSsid is refused outright - an empty SSID is what drops AWTRIX into AP mode. Each answers 422 validationFailed with the key in field:

Unknown keys are still ignored (the route is a partial merge) and every other string is stored as sent. The deeper GPIO rules - duplicate pins, input-only pins, the matrix driver whitelist - still answer 400 invalidPinConfig rather than 422; see GPIO validation.

GPIO validation (invalidPinConfig)¶

PUT /api/v1/system is the only route that emits this code. The incoming fields are merged onto a scratch copy of the configuration and the whole resulting pin map is validated before anything is written - so a rejected request changes nothing, and a single valid-looking field can still fail because of how it combines with the pins already stored.

The status is 400, and there is no field - the offending pin's name is in the message:

Each message is built from the running chip's rules, so the numbers above are the ESP32's and an ESP32-S3 answers with its own. The per-chip values are in Rules come from the chip and in GET /api/v1/capabilities.

curl -i -X PUT http://<awtrix-ip>/api/v1/system \
  -H 'Content-Type: application/json' \
  -d '{"pinBuzzer":34}'
# HTTP/1.1 400 Bad Request
# {"error":{"code":"invalidPinConfig","message":"pinBuzzer: GPIO 34-39 are input-only"}}

Errors over MQTT¶

MQTT has no status codes. A command result is published as a JSON object whose ok field carries the verdict; failures embed the same error object:

{"ok":false,"error":{"code":"validationFailed","message":"out of range","field":"brightness"}}

Success is {"ok":true}. Eight codes can appear over MQTT:

The other ten codes are HTTP-only. methodNotAllowed, unauthorized, forbidden, unsupportedMediaType, payloadTooLarge and invalidMethodOverride describe request framing, which MQTT has no equivalent for; invalidPath, badRequest and wrongChip belong to the upload routes, and invalidPinConfig to PUT /api/v1/system - none of which MQTT can reach.

A published command over the MQTT payload ceiling is dropped before it is parsed, so it produces no /result reply at all rather than a payloadTooLarge.

Responses that look like errors but are not¶