Errors

Wallpaper Server reports errors as plain-text response bodies with a standard HTTP status code. Responses are not JSON, and there are no stable machine-readable error codes. Check the status code, and treat the body as a human-readable message that may change.

Status codes

Status	Meaning	Common causes
401 Unauthorized	Remote administration without an accepted bearer token	Upload, delete, refresh or settings from a non-loopback peer
403 Forbidden	Administrative request with a disallowed Origin header	Cross-origin administration attempt
400 Bad Request	The request was malformed	Invalid wallpaper ID, missing file field on upload, an unsupported file extension
404 Not Found	Nothing matched	No wallpaper matches the given filters; unknown {id}; unknown route
405 Method Not Allowed	Wrong HTTP method	For example POST to a GET-only endpoint
500 Internal Server Error	The server failed to complete the request	Filesystem or image-processing failure
503 Service Unavailable	The server cannot serve settings	The configuration file path is not set

Example error bodies

Invalid wallpaper ID

unsupported file extension: .gif

Missing 'file' field

Method not allowed

Handling errors in scripts

Because the body is plain text, branch on the status code rather than parsing the body. With curl, use --fail so a non-2xx response produces a non-zero exit code:

if curl --fail --silent \
  "http://localhost:8519/api/wallpapers/random/image?brightness=dark" \
  --output wallpaper.jpg; then
  echo "Got a wallpaper"
else
  echo "Request failed (no match or server error)"
fi

See Shell and cron for a safe download pattern that avoids overwriting a good wallpaper on failure.