Errors¶

What AWTRIX answers when a request fails: the error body, every error code, and the messages for the most common mistakes. Error codes lists every code the API returns.

The error body¶

Every failed HTTP request gets a JSON answer in this shape:

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

The one exception is POST /api/v1/restore - see Restore result.

Restore result¶

Once a backup file arrives, POST /api/v1/restore answers with this object instead, whether the restore worked or not:

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

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

These answers use the normal error body instead:

• The upload ends without a file in it: 400 with {"error":{"code":"badRequest","message":"no file received"}}.
• The backup was restored, but AWTRIX could not save it yet: 507 insufficientStorage, restored, not saved yet. Free storage and repeat the restore before rebooting.
• Login is on and the credentials are wrong: 401 unauthorized.

Error codes¶

field is present when one key is at fault. Clients must allow it to be absent with any error code. For example, renaming an icon can report invalidName with from or to, or nameTaken with to; a melody body that is not valid JSON reports invalidJson with rtttl.

How large a body may be and how many apps and notifications fit: Limits.

Status codes¶

File uploads return 507 insufficientStorage with write failed if the file cannot be written or published. The existing destination is retained; a directory created for that failed upload is removed when empty. Each file in a multipart request is published separately: a later failure does not undo earlier successful files.

App order and radio station changes return 507 insufficientStorage with applied, not saved yet when the new state is active but could not be saved. The previous saved file remains intact. Free storage and repeat the request before rebooting.

A 507 for a full store or queue reads storage full. A script install refused for lack of memory has its own message and field: "name" or field: "source" - see Script installation.

device/reboot, device/sleep, device/factory-reset and settings/reset send their 200 {"ok":true} before AWTRIX restarts or goes to sleep, so you always get the answer.

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¶

A wrong method on a supported route below answers 405, and the message is allowed: <list>. An unknown path answers 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: POST"}}

/api/v1/restore is a route for POST only: any other method answers 404 unknown route.

Order of the checks¶

AWTRIX checks a request in this order and answers the first problem it finds:

1. Login: 401.
2. How the request is sent: a bad method override (400 invalidMethodOverride), a page of another site on a protected route (403 forbiddenOrigin), a body that is too large (413), a Content-Type other than JSON on a PUT or PATCH (415).
3. The method: 405.
4. The app name in the path: 400 invalidName.
5. The body: 400 invalidJson, then 422 validationFailed.

So PATCH /api/v1/apps/pushed/bad.name answers 405 allowed: PUT, not 400. A PUT to /api/v1/apps/script/ without a name, sent as text/plain, answers 415: without a name the path is no script upload, so the Content-Type rule applies.

Two paths check their name before the method:

• /api/v1/apps/{name}: a path without a valid name answers 400 invalidName, not 405. This is what a bare sub-path like /api/v1/apps/script/ gets: script/ is not a valid app name.
• /api/v1/indicators/{id}: an {id} other than 1, 2 or 3 answers 404 id must be 1..3.

curl -i -X GET http://<awtrix-ip>/api/v1/apps/script/
# HTTP/1.1 400 Bad Request
# {"error":{"code":"invalidName","message":"invalid name","field":"name"}}

active, next, previous and order are their own routes with their own methods. DELETE /api/v1/apps/next answers 405 allowed: POST - it does not delete an app called next.

Authentication (401)¶

Login is off by default. It turns on only when you set authEnabled (PUT /api/v1/system), and that needs both authUser and authPass - a username alone changes nothing. Once on, it applies in every mode, also in setup mode. In setup mode AWTRIX also answers far fewer routes (see Setup mode lockdown), so a stranger in range cannot use the write API even before you set a password.

When login is on and your request has no or wrong credentials, AWTRIX answers:

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 makes a browser show its login window.
• The body is JSON in the normal error shape, not HTML.
• Login protects everything AWTRIX serves: the web UI at /, the files under /ICONS/, /MELODIES/ and /PALETTES/, and the upload routes POST /update and POST /api/v1/files.

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

Setup mode lockdown (403)¶

While AWTRIX is in setup mode, these are the only available routes:

Logs, scripts, file lists, secrets export and all other API routes are refused. A system update with other fields, duplicate fields or malformed JSON is refused as well. The response is:

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

{"error":{"code":"forbidden","message":"Wi-Fi setup only"}}

The same refusal applies to file and firmware uploads. Any request with a secrets query parameter is refused, even ?secrets=0. Requests from another web origin are also refused. The setup hotspot itself has no password; if you have set a web login, it is still required for the allowed routes.

Content-Type: the empty-body trap¶

On PUT and PATCH, AWTRIX rejects a body only when the request has a Content-Type header that is not application/json. The header itself is not required. POST is not checked.

Exceptions: PUT /api/v1/apps/script/{name} takes Berry source and accepts any content type. PUT /api/v1/apps/script-update/{name} also accepts any content type, but its body must still be JSON. See installing a script.

The trap is curl -d: it sends Content-Type: application/x-www-form-urlencoded unless you set another one - and that is what fails:

• A Content-Type that is not application/json gets 415 unsupportedMediaType (expected application/json) before the body is read. This is what a curl -d without -H gets.
• A request with no Content-Type header at all passes; the body is read as JSON.
• On a POST, the header is not checked. A JSON body sent with the form type of curl -d is read as JSON like any other, so POST /api/v1/notifications with it shows the notification.
• An empty or {} body on a route that needs content gets 422 validationFailed with the message body required.

On the other routes, an empty body and {} behave differently: an empty body is never valid JSON, while {} is a valid object with nothing in it.

An empty body never deletes or turns anything off. To delete an app, turn the mood light off or clear an indicator, use its DELETE route (or, over MQTT, send an empty payload to clear).

Always send the header:

# 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 its key in field. These are the messages you can get.

PATCH /api/v1/settings¶

All keys are checked before anything is changed. The first invalid key 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"}}

Script installation¶

PUT /api/v1/apps/script/{name} returns 507 insufficientStorage for these limits. A 507 has one of five messages. Each needs a different fix:

"All scripts together too large" applies only to new names. Replacing an installed script is never refused for that reason. The other four apply to replacements too. A shorter script may still install when a longer one was refused. All limits: Limits.

Audio playback¶

The body is checked before stored files and audio hardware. Inside a list, field starts with the entry position, for example [1].rtttl. These messages have status 422 validationFailed:

Playback can also fail after validation:

Other routes¶

Two routes check less:

• PUT /api/v1/display/moodlight rejects an empty or {} body with 422 (above). A bad brightness or kelvin value is cut to fit instead of rejected. A color that is not a color gets 422 validationFailed with field: "color", as on PUT /api/v1/indicators/{id}.
• PUT /api/v1/apps/active reads the body as the app name as it is, so a malformed body answers 404 app not found, not 400.

Per-app effect and overlay names¶

A pushed app or notification with an unknown effect or overlay gets 422 validationFailed with field: "effect" or field: "overlay", and nothing is stored. In an array payload, one bad element rejects the whole array. The accepted names are listed by GET /api/v1/capabilities. The global overlay on PATCH /api/v1/display is checked the same way.

PUT /api/v1/system¶

Every number is checked for type and range before anything is saved. A rejected request changes nothing, and field names the 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, panelWiring and panelColorOrder answer must be one of: <names>. panelSerpentine, mirror and rotate answer must be a boolean.

These rules look at several keys together. They are checked against the result after your change, so a request that sets only one of the keys is checked too:

The five static-address fields - ip, gateway, subnet, dns1, dns2 - must be an address like 192.168.1.50 (no leading zeros) or the empty string. 0.0.0.0 as gateway or DNS server means none. ip may also include the mask (192.168.1.50/24); it is then saved as separate ip and subnet values.

Anything else answers must be IPv4 or "", on ip must be IPv4, IPv4/prefix or "". Sending a /prefix on ip and a subnet in the same request answers 422 on subnet: mask already set on ip.

Some switches need other keys first. Each answers 422 validationFailed with the key in field:

wifiSsid cannot be emptied, because an empty Wi-Fi name puts AWTRIX into setup mode. Unknown keys on this route are ignored, and other text fields are saved as sent. Pin conflicts - two functions on one pin, input-only pins, an unsupported LED data pin - answer 400 invalidPinConfig instead; see GPIO validation.

GPIO validation (invalidPinConfig)¶

Only PUT /api/v1/system returns this code. AWTRIX checks all pins together, as they would be after your change, before saving anything. So a rejected request changes nothing, and a single pin that looks fine can still fail because it clashes with a pin already set.

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

Names and ranges in angle brackets depend on the selected pins and chip. The values per chip 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 26-37 are reserved for the SPI flash and PSRAM"}}

Errors over MQTT¶

MQTT has no status codes. The result of a command is published as a JSON object; ok says whether it worked. A failure contains the same error object as over HTTP:

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

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

All other codes are HTTP only. methodNotAllowed, unauthorized, forbidden, forbiddenOrigin, unsupportedMediaType, payloadTooLarge and invalidMethodOverride are about how an HTTP request is sent. invalidPath, badRequest and wrongChip belong to uploads and updates, and invalidPinConfig to PUT /api/v1/system. MQTT reaches none of these.

Every rejected command, over MQTT or HTTP, is also published on <P>/event/error, so one subscription shows all of them.

A command larger than the MQTT size limit is dropped unread. You get no /result reply at all, not a payloadTooLarge.

Responses that look like errors but are not¶

Related¶

• Conventions
• Limits
• HTTP API
• MQTT API