# Responses and errors

> The response envelope, IDs, browser access and every error code.

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

## Successful responses

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

```json
{
  "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](https://docs-preview.mediux.io/api/guides/image-urls.md).
- 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.

## IDs

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.

## Browsers

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.

## Errors

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`):

```json
{
  "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.

### Error codes

| Code | Status | Meaning |
| ---- | ------ | ------- |
| `request.invalid` | 400 | The request body or a parameter isn't valid; see `issues`. |
| `route.invalid` | 400 | The path, or an ID in it, isn't valid. |
| `route.queryNotSupported` | 400 | Public paths take no query string. |
| `auth.required` | 401 | No access token was sent. |
| `auth.invalidToken` | 401 | The token is malformed, expired or revoked. Refresh it or connect again. |
| `auth.insufficientScope` | 403 | The user didn't grant the App Permission this route needs. |
| `auth.forbidden` | 403 | The app or the user can't do this, for example on someone else's resource. |
| `resource.notFound` | 404 | Nothing exists at this path. |
| `request.methodNotAllowed` | 405 | The route doesn't accept this method. Public routes take `GET` and `HEAD`. |
| `resource.conflict` | 409 | The change conflicts with the resource's current state or a limit; see `details`. |
| `resource.gone` | 410 | The resource existed but was removed. |
| `request.lengthRequired` | 411 | A request body needs a `Content-Length` header. |
| `upload.tooLarge` | 413 | The request body is larger than the route accepts. |
| `upload.unsupportedType` | 415 | The request body's media type isn't accepted. |
| `entity.notInMediux` | 422 | The title isn't on Mediux yet. Add it on mediux.io first. |
| `request.rateLimited` | 429 | Too many requests. Wait for `Retry-After`, or 10 minutes when it's absent. |
| `service.unavailable` | 503 | Mediux is briefly unavailable. Wait for `Retry-After`. |

OAuth endpoints use the standard OAuth `error` field instead; see
[Authentication](https://docs-preview.mediux.io/api/authentication.md).

### Business-rule codes

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

| Code | Status | Meaning |
| ---- | ------ | ------- |
| `list.invalidInput` | 400 | A List field isn't valid; see `issues`. |
| `list.notFound` | 404 | No such List for this user: one they don't own, or, to subscribe, one that isn't Public. |
| `list.itemUnavailable` | 404 | A title isn't on Mediux, or an Asset no longer exists. Nothing was added. |
| `list.itemIneligible` | 409 | That item can't go on a List, such as a Boxset or Loadout poster. |
| `list.kindMismatch` | 409 | Wrong route for this kind of List: titles on an Asset List, or Assets on a Media or Game List. |
| `list.subscriptionInvalid` | 409 | Users can't subscribe to their own List. |
| `list.limit.lists` | 409 | The user already owns 100 Lists. |
| `list.limit.subscriptions` | 409 | The user already subscribes to 500 Lists. |
| `list.limit.images` | 409 | The Asset List is full (about 1,000 images). |
| `list.limit.entities` | 409 | The Media or Game List is full (500 titles). |
| `relationship.self` | 422 | Users can't follow or hide themselves. |

### Retries

- **`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.
