# Errors

## The REST error shape

Every REST error has the same body:

```json
{
  "error": {
    "type": "authentication_error",
    "code": "unknown_key",
    "message": "The API key is missing, unknown or revoked.",
    "requestId": "01a135cb-0fae-746c-bc27-a0a912c82989"
  }
}
```

- `type` is the kind of error. Branch on it, or on `code`.
- `code` is the exact reason. It never changes for the same reason.
- `message` is for people. It can change; do not parse it.
- `requestId` is the same value as the `x-correlation-id` response header. Give it to Passion
  support when you ask about a request.

## Types and codes

| Status | `type` | `code` | When |
| --- | --- | --- | --- |
| 400 | `invalid_request_error` | `invalid_input` | The input is not valid, for example an empty title. |
| 400 | `invalid_request_error` | `unknown_version` | The `Passion-Version` header names a version that does not exist. |
| 401 | `authentication_error` | `unknown_key` | The key is missing, unknown or revoked. |
| 403 | `permission_error` | `app_not_granted` | The key does not reach this App. |
| 403 | `permission_error` | `write_scope_required` | A read key asked for a change. |
| 500 | `api_error` | `internal_error` | Something failed on our side. Try again later. |

A refused request changes nothing. A path that is not a route gets a plain `404` without this
body.

## Errors in the MCP

- A request without a working key gets HTTP `401` and a JSON-RPC error with the code `-32001`.
- A tool call that is refused, for example about an App the key does not reach, returns a tool
  result with `isError: true`. Its text is the same message that the REST API gives.
- A request from a web page on another site gets `403`.
- A method other than `POST` gets `405`.