> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.homemediadb.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.homemediadb.com/_mcp/server.

# Errors

Errors follow the standard tRPC envelope. Over HTTPS, the response carries an `error` object and an appropriate HTTP status code derived from the tRPC error code:

```json
{
  "error": {
    "json": {
      "message": "Release not found",
      "code": -32004,
      "data": {
        "code": "NOT_FOUND",
        "httpStatus": 404
      }
    }
  }
}
```

Check `error.json.data.code` (or the HTTP status) to branch on the error; `code` is the tRPC numeric code and isn't meant for application logic.

## Status codes

| HTTP  | Code                    | Meaning                                                                                        |
| ----- | ----------------------- | ---------------------------------------------------------------------------------------------- |
| `400` | `BAD_REQUEST`           | Input failed validation: wrong type, or a missing required field.                              |
| `401` | `UNAUTHORIZED`          | No valid API key. Send one as `Authorization: Bearer ak_…`.                                    |
| `403` | `FORBIDDEN`             | Authenticated, but not allowed, e.g. editing someone else's review, or a staff-only procedure. |
| `404` | `NOT_FOUND`             | The requested resource does not exist.                                                         |
| `409` | `CONFLICT`              | The action clashes with current state, e.g. a second review of the same release.               |
| `429` | `TOO_MANY_REQUESTS`     | Rate-limited. Back off and [slow down](/authentication#be-considerate).                        |
| `500` | `INTERNAL_SERVER_ERROR` | Something went wrong on our side.                                                              |

Each procedure in the [API reference](/api-reference) lists the specific errors it can return.