Skip to content
MediuxDocs

Responses and errors

Every response follows the same few rules, and every error carries a stable code you can branch on.

Every JSON response puts its result in data. Lists of things add a meta object with paging or chunk details.

{
"data": { "kind": "show", "id": 1399, "title": "Game of Thrones" },
"meta": {}
}
  • Field names are camelCase, and so are enum values such as movieSet.
  • Instants end in At and are ISO 8601 UTC with milliseconds, such as 2026-11-14T15:03:02.000Z. Dates without a time, such as releaseDate, are YYYY-MM-DD.
  • A reference to another resource is { "kind": "...", "id": ... }, plus a few display fields.
  • Images are { "id": "...", "extension": "png" }; see Build image URLs.
  • YAML routes return text as application/yaml; charset=utf-8.
  • Text from TMDB and IGDB, such as titles, overviews, taglines and names, is in English only. There’s no language parameter.

Each endpoint page lists every field of its response.

Titles, People, Networks, Companies, Categories, Sets, Boxsets and Loadouts have numeric Mediux IDs, such as 1399; a title’s IMDb, TVDB and other IDs are in its externalIds. Lists and Assets use lowercase UUIDs. User paths take the username in lower case (/users/koltom; a UUID there is 400 route.invalid), and a user’s UUID id appears only in response bodies. A malformed ID returns 400; an ID that doesn’t exist returns 404, or 410 if it was removed.

Any website can call the Public API. Cross-origin GET and HEAD requests work without credentials, preflight OPTIONS is answered for you, and your code can read the ETag and Retry-After headers. The Protected API is for servers and native apps: keep its tokens out of web pages.

Check the HTTP status first: rate limits and outages from the network edge can return a body in another format. Then branch on error.code, never on the message, which can change.

Every error, Public or Protected, has data: null, the code, a short message and a link to the code’s entry below. Some add details (limits such as maxItems) and issues (each failing field, with its path):

{
"data": null,
"error": {
"code": "request.invalid",
"message": "The request is invalid",
"requestId": "8f0c2a1b3d4e5f60",
"docs": "https://docs.mediux.io/api/errors#request-invalid",
"issues": [{ "code": "request.tooBig", "path": ["titles"] }]
}
}

Protected errors always carry requestId. Public errors are often served from the edge cache to many callers, so they leave it out.

Quote requestId, or the cf-ray response header when it’s absent, if you ask for help. Don’t pass tokens or request headers on in your own app’s errors.

CodeStatusMeaning
request.invalid400The request body or a parameter isn't valid; see issues.
route.invalid400The path, or an ID in it, isn't valid.
route.queryNotSupported400Public paths take no query string.
auth.required401No access token was sent.
auth.invalidToken401The token is malformed, expired or revoked. Refresh it or connect again.
auth.insufficientScope403The user didn't grant the App Permission this route needs.
auth.forbidden403The app or the user can't do this, for example on someone else's resource.
resource.notFound404Nothing exists at this path.
request.methodNotAllowed405The route doesn't accept this method. Public routes take GET and HEAD.
resource.conflict409The change conflicts with the resource's current state or a limit; see details.
resource.gone410The resource existed but was removed.
request.lengthRequired411A request body needs a Content-Length header.
upload.tooLarge413The request body is larger than the route accepts.
upload.unsupportedType415The request body's media type isn't accepted.
entity.notInMediux422The title isn't on Mediux yet. Add it on mediux.io first.
request.rateLimited429Too many requests. Wait for Retry-After, or 10 minutes when it's absent.
service.unavailable503Mediux is briefly unavailable. Wait for Retry-After.

OAuth endpoints use the standard OAuth error field instead; see Authentication.

Protected routes add their own codes, named area.reason:

CodeStatusMeaning
list.invalidInput400A List field isn't valid; see issues.
list.notFound404No such List for this user: one they don't own, or, to subscribe, one that isn't Public.
list.itemUnavailable404A title isn't on Mediux, or an Asset no longer exists. Nothing was added.
list.itemIneligible409That item can't go on a List, such as a Boxset or Loadout poster.
list.kindMismatch409Wrong route for this kind of List: titles on an Asset List, or Assets on a Media or Game List.
list.subscriptionInvalid409Users can't subscribe to their own List.
list.limit.lists409The user already owns 100 Lists.
list.limit.subscriptions409The user already subscribes to 500 Lists.
list.limit.images409The Asset List is full (about 1,000 images).
list.limit.entities409The Media or Game List is full (500 titles).
relationship.self422Users can't follow or hide themselves.
  • 429: wait for Retry-After. A 429 without it comes from the network edge: back off for at least 10 minutes.
  • 503: wait for Retry-After, then try again.
  • A write whose response was lost: it may or may not have happened. Read the resource and compare before you write again.