Errors

All errors are JSON unless the endpoint returns binary content. The shape is always:

{
  "error": "Human readable message",
  "code": "machine_readable_code"
}

Status codes

400 Bad Request

A required query parameter is missing, or one of the values is malformed. The error field tells you which.

401 Unauthorized

No valid User-Agent header. See authentication.

404 Not Found

The track, artist, album or playlist you asked for does not exist in any of the upstream sources. This is a real "we looked and could not find it", not a bad route.

429 Too Many Requests

You exceeded the rate limit. Wait Retry-After seconds and try again. See rate limits.

500 Internal Server Error

Something on our side failed. These get logged and looked at, but the request itself is not safe to retry blindly. Back off with a small delay before trying again.

502 / 503 / 504

An upstream provider (Spotify, MusicBrainz, etc.) is down or slow. Retry with exponential backoff. Most of these clear inside 30 seconds.