# Errors

## Summary

Every failure of the API has the same shape: an HTTP status, an error `code`, a
message for people and machine-readable `details`. This page lists every code
the API can answer, its status, every `details.reason` it can carry, what each
one means and what to do about it. It also covers the three places where the
shape differs: the OAuth endpoints, MCP protocol errors and the files host.

Branch on `code` and on `details.reason`. Never branch on `message`: its
wording can change.

## The error envelope

Every error from `/v1` has this JSON body:

```json
{
  "error": {
    "code": "VALIDATION_FAILED",
    "message": "name must not contain control characters",
    "details": { "field": "name" }
  },
  "requestID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17"
}
```

- `error.code` is one of the 20 codes below.
- `error.message` is English text that is safe to show to a person.
- `error.details` is always present. It is an object, or `null` when the code
  has nothing to add.
- `requestID` identifies the request. The same value is in the `x-request-id`
  response header. Quote it when you ask for help.
- Some codes add a response header. The table says which.
- Every operation can answer `500 INTERNAL` and `503 TIMEOUT`, whatever else it
  documents.

## Every code

| Code | HTTP status | `details` | Headers | Meaning |
| --- | --- | --- | --- | --- |
| `UNAUTHENTICATED` | 401 | `null`, or `reason`: `INVALID_TOKEN` or `AMBIGUOUS_CREDENTIALS` | `WWW-Authenticate` for `INVALID_TOKEN` | No valid session or bearer token. |
| `INVALID_CREDENTIALS` | 401 | `null` | | The email or the password is wrong at sign-in. |
| `FORBIDDEN` | 403 | `null`, or `reason`: `SESSION_REQUIRED`, `HUMAN_APPROVAL_REQUIRED`, `INSUFFICIENT_SCOPE` (with `requiredScopes`) or `MAKES_FILES_PUBLIC` (with `becomePublic`) | `WWW-Authenticate` for `INSUFFICIENT_SCOPE` | You are known, but may not do this. |
| `EMAIL_NOT_VERIFIED` | 403 | `null` | | The action needs a verified email address. |
| `SIGNUP_CLOSED` | 403 | `null` | | Sign-up is closed to this address. |
| `NOT_FOUND` | 404 | `null` | | The thing does not exist, or you cannot reach it. |
| `METHOD_NOT_ALLOWED` | 405 | `null` | `Allow` | The path exists but not with this HTTP method. |
| `VALIDATION_FAILED` | 422 | `field`, or `null` | | The request is malformed or a value breaks a rule. |
| `TOKEN_INVALID` | 400 | `null` | | An emailed link is unknown, expired, used or replaced. |
| `STALE_FILE_VERSION` | 409 | `currentVersionID` | | The file got a newer version since the one you based a replacement on. |
| `STALE_LOCK_VERSION` | 409 | `currentLockVersion` | | The file or folder changed since you read it. |
| `CONFLICT` | 409 | `null`, or `reason` (21 values, below) | | The request conflicts with the current state. |
| `SOLE_OWNER` | 409 | `organizationIDs` | | The action would leave an organization without an owner. |
| `PAYLOAD_TOO_LARGE` | 413 | `limitBytes`, or `null` | | A body, a file or an answer is over a size limit. |
| `UNSUPPORTED_MEDIA_TYPE` | 415 | `null` | | The file type or the request's content type is not accepted. |
| `RANGE_NOT_SATISFIABLE` | 416 | `sizeBytes` | `Content-Range: bytes */<size>` | The requested byte range starts past the end of the content. |
| `RATE_LIMITED` | 429 | `retryAfterSeconds` | `Retry-After` | Too many attempts in the current time window. |
| `INTERNAL` | 500 | `null` | | An unexpected failure on our side. |
| `UNAVAILABLE` | 503 | `reason` (5 values, below) | `Retry-After` for `IMAGE_SERVICE_UNAVAILABLE` and `IMAGE_RENDER_TIMED_OUT` | Something the request depends on is not available right now. |
| `TIMEOUT` | 503 | `null` | | The request ran past its time limit. |

## Code by code

### `UNAUTHENTICATED` (401)

| `details.reason` | Message | When | What to do |
| --- | --- | --- | --- |
| none (`details` is `null`) | "Authentication required" | A session operation was called without a live session cookie, or `/mcp` or `GET /v1/credential` was called without a bearer token. | Sign in, or send `Authorization: Bearer <token>`. |
| `INVALID_TOKEN` | "The bearer token is invalid, expired or revoked" | The bearer token is malformed, unknown, expired or revoked. Its member left or was removed from the organization, or deleted their account. Its organization is deleted. The `Authorization` header uses another scheme than `Bearer`. An OAuth access token was sent to `/v1`. A refresh token was sent as a bearer token. | Check the token. Create a new key or reconnect the app. One answer covers every cause, so the response never says which. |
| `AMBIGUOUS_CREDENTIALS` | "Send either a session cookie or a bearer token, not both" | A request to `/v1` carried a session cookie and a bearer token together. | Send one of the two. A script should send no cookies. |

- `INVALID_TOKEN` carries `WWW-Authenticate: Bearer error="invalid_token"`.
- A token that does not authenticate answers `INVALID_TOKEN` on every
  browser-only operation and on every operation a credential may call,
  before anything else about the operation is checked. Each such answer
  counts as a failed authentication of the client address.
- An operation that needs no sign-in ignores the `Authorization` header,
  whatever it holds: nothing is authenticated and nothing is counted. A
  bearer token sent together with a session cookie still answers
  `AMBIGUOUS_CREDENTIALS` there.
- At `/mcp`, a missing token carries
  `WWW-Authenticate: Bearer resource_metadata="<app origin>/.well-known/oauth-protected-resource/mcp"`,
  and an invalid one carries `error="invalid_token"` and the same
  `resource_metadata`.
- In the web app any `UNAUTHENTICATED` answer sends the person to sign-in.

### `INVALID_CREDENTIALS` (401)

- Message: "Email or password is incorrect".
- Sign-in answers it for an unknown email and for a wrong password alike.
- What to do: check both, or reset the password.
- A wrong current password inside the app (changing the password or the email,
  deleting the account) is not this code: it is `VALIDATION_FAILED` on
  `currentPassword`.

### `FORBIDDEN` (403)

| `details.reason` | Message | When | What to do |
| --- | --- | --- | --- |
| none (`details` is `null`) | "Forbidden" | Your role does not allow the action (for example a member changing organization folder files or managing members). A request that changes something sent an `Origin` header that is not the app's own. A session cookie was sent on a changing request without an `Origin` header. A member asked for the `files:approve` scope on a key or at consent. An invitation was accepted by an account with another email address. A request to `/mcp` sent an `Origin` header that is not allowed. | Ask an owner or admin, or fix the request. A script should not send `Origin`. |
| `SESSION_REQUIRED` | "This operation needs a person signed in with a browser" | A bearer token called an operation that only a browser session may call. | Do it in the web app. See [The REST API](../agents/rest-api.md#access-classes). |
| `HUMAN_APPROVAL_REQUIRED` | "Approvals need a person signed in with a browser" | A bearer token tried to apply a library proposal. | A person applies the proposal in the web app. |
| `INSUFFICIENT_SCOPE` | "This credential does not have the scope this operation needs" | The credential lacks the operation's scope. Also when a move through a credential would make files public and the credential lacks `files:approve`. `details.requiredScopes` lists the scope. | Create a credential with that scope, or do something that needs less. |
| `MAKES_FILES_PUBLIC` | "This would make files public; only an owner or admin can do that" | A move or an applied proposal would make files public, and the person (or the member a credential acts for) is not an owner or admin. `details.becomePublic` is the number of files. Nothing changed. | Ask an owner or admin, or choose a destination that is not public. |

- `INSUFFICIENT_SCOPE` carries
  `WWW-Authenticate: Bearer error="insufficient_scope", scope="<scope>"`.
- Over MCP a missing scope does not answer `INSUFFICIENT_SCOPE` for a whole
  tool: the tool is simply not listed and calling it is an unknown-tool error.
  `INSUFFICIENT_SCOPE` still reaches MCP callers for moves that would make
  files public.

### `EMAIL_NOT_VERIFIED` (403)

- Message: "Verify your email address first".
- Answered for: deleting an organization, deleting a workspace, and setting
  file statuses or making files public by a move through a credential whose
  member has not verified their email.
- Never answered for deleting your own account, which needs no verified
  email.
- It is checked after the role check.
- What to do: open the verification link, or use "Resend verification email"
  in the app.

### `SIGNUP_CLOSED` (403)

- Message: "Sign-up is by invitation".
- Answered at sign-up while sign-up is closed, for an address that is not
  admitted and brings no live invitation to that address.
- The answer is the same whether or not the address has an account.
- What to do: sign up from the invitation link you received, or sign in if you
  have an account.

### `NOT_FOUND` (404)

- Message: "Not found".
- Answered for an unknown ID, a malformed ID in a path, an ID in another
  organization or workspace, an ID a credential's workspaces do not cover, a
  deleted organization or workspace, a purged file, and an unknown path.
- All of these look the same on purpose, so an answer never reveals whether
  something exists elsewhere.
- Refusals come in a fixed order: `404` first, then `403` for the role, then
  `422` for validation.
- What to do: check the ID and that the credential covers its workspace. Call
  `workspaces_list` (or `GET /v1/workspaces`) to see what a credential reaches.

### `METHOD_NOT_ALLOWED` (405)

- Message: "This method is not allowed on this path".
- `/mcp` accepts only `POST` and answers anything else with `Allow: POST`.

### `VALIDATION_FAILED` (422)

- `details.field` names the input that failed, when one input did. The message
  says what is wrong.
- A body that is not valid JSON, a missing required property, a value of the
  wrong type, an unknown enum value or an invalid query parameter answers
  `VALIDATION_FAILED` with `details: null`.
- Over MCP, a bad argument answers the same code with `details.field`.

Values of `details.field`, by area:

| Area | `details.field` values |
| --- | --- |
| Lists | `cursor`, `limit` |
| Creates that can be repeated | `requestID` |
| Accounts | `email`, `password`, `newPassword`, `currentPassword`, `newEmail`, `fullName` |
| Organizations and workspaces | `name`, `workspaceName`, `confirmName`, `workspaceIDs` |
| Credentials and connected apps | `name`, `organizationID`, `workspaceIDs`, `scopes`, `expiresInDays`, `overlapHours` |
| Files | `name`, `altText`, `description`, `caption`, `tags`, `folderID`, `fields`, `fileIDs`, `field`, `status`, `root`, `trash` |
| Folders | `name`, `parentID` |
| Statuses and fields | `name`, `statuses`, `fields`, `statusID`, `statusIDs`, `fieldIDs`, `choices`, `choiceIDs` |
| Uploads | `fileName`, `sizeBytes`, `sha256`, `folderID`, `baseVersionID` |
| Library proposals | `summary`, `items`, `payload`, `rationale` |
| Favorites | `favoriteIDs` |
| Image delivery | `options`, `image`, `asset` |

Rules that apply to every text input:

- Text must not contain control characters. `"Name\n"` is refused, not trimmed
  to `Name`.
- Names are trimmed before their length is checked.
- Descriptions, captions and text field values allow line breaks and tabs.
  Alt text does not: it is one line.
- A tag holds no comma. One that does is refused with the message "a tag
  cannot contain a comma": on `tags` when it is set on a file or named in an
  `add_tag` or `remove_tag` item of a suggestion, on `name` when a tag is
  renamed to it.
- A full list answers on its own field, not on `name`. A 51st status answers
  on `statuses` ("a file space has at most 50 statuses"), a 51st custom
  field on `fields` ("a file space has at most 50 fields") and a 101st
  choice of a field on `choices` ("a field has at most 100 choices"). The
  app says "An organization can have up to 50 statuses. Delete one to add
  another.", "An organization can have up to 50 custom fields. Delete one to
  add another." and "A field can have up to 100 options. Delete one to add
  another."
- In the app, a name, description, caption or alt text refused for a control
  character shows "Remove the tab or other character that cannot be saved."
  under that input.

### `TOKEN_INVALID` (400)

- Message: "This link is invalid or has expired".
- Answered for an emailed link (email verification, password reset, email
  change, invitation) that is unknown, expired, already used, replaced by a
  newer link, revoked, or that belongs to a deleted organization.
- One code covers every cause.
- What to do: ask for a new link. In the app this reads "Link expired or
  invalid".
- This code is about emailed links only. A bad bearer token is
  `UNAUTHENTICATED` `INVALID_TOKEN`.

### `STALE_FILE_VERSION` (409)

- Message: "This file changed since you opened it".
- `details.currentVersionID` is the file's current version.
- Answered when an upload that replaces a file names a `baseVersionID` that is
  no longer the file's current version.
- What to do: read the file again, decide whether your replacement still
  applies, and start the upload again with the current version as
  `baseVersionID`.

### `STALE_LOCK_VERSION` (409)

- Message: "This changed since you opened it".
- `details.currentLockVersion` is the current lock version.
- Answered when a change to a file or folder sends an `expectedLockVersion`
  that is no longer current.
- What to do: read the file or folder again, apply your change to what you
  read, and send it with the new `lockVersion`.
- See [The REST API](../agents/rest-api.md#lock-versions).

### `CONFLICT` (409)

`details.reason` names the conflict. Every reason:

| `details.reason` | When | What to do |
| --- | --- | --- |
| `NAME_TAKEN` | A sibling folder has the name, ignoring case. A tag, a file status, a file field or a choice of the same field has the name. A workspace is created, renamed or restored while a live workspace of the organization has the name. | Choose another name, or rename the other one first. |
| `CYCLE` | A folder is moved into itself or into a folder below it. | Choose another destination. |
| `IN_TRASH` | A trashed file or folder is changed, trashed again, given a status or a field value, made public, replaced by an upload or asked for a signed URL. In a batch, one trashed file refuses the whole batch. | Restore it first, or leave it out of the batch. |
| `NOT_IN_TRASH` | A live file or folder is restored or purged. Also a file or folder that went to the trash along with a folder: it restores and purges only with that folder. | Nothing to restore; or restore the folder that took it along. |
| `NOT_PENDING` | An upload that is no longer pending is cancelled, or a cancelled upload is completed. | Start a new upload if you still need one. |
| `OBJECT_MISSING` | An upload is completed before its bytes arrived. The upload stays pending. | PUT the bytes, then complete again. |
| `EXPIRED` | An upload is completed after it expired. | Start a new upload. |
| `DIFFERENT_TYPE` | A replacement upload is of another file type than the file's current version. | Replace it with a file of the same type, or upload it as a new file. |
| `REQUEST_REUSED` | A `requestID` is repeated with a different body or in another workspace within 24 hours. | Use a new `requestID` for a new request. Repeat the exact request to retry. |
| `STATUS_BLOCKS_PUBLIC` | A file is made public while it has no status, or a status that does not allow public use. | An owner or admin first sets a status that allows public use. |
| `VISIBILITY_CHANGE` | A move or a status change would start or stop public links, and the request did not confirm it. `details.becomePublic` and `details.stopPublic` count the files. `details.publicVia` is `{id, name}` of the folder that shares the destination, or `null`. Nothing changed. | Show the counts to a person, then repeat the request with `confirmVisibilityChange: true`. |
| `DEFAULT_ALLOWS_PUBLIC` | A status change would leave the default status allowing public use. | Keep the default status one that does not allow public use. |
| `LAST_WORKSPACE` | The organization's only live workspace is deleted. | Create another workspace first, or delete the organization. |
| `CONNECTION_LIMIT` | An app's request to connect is allowed while you already hold 10 working connections to that app in that organization. The request stays open. | Disconnect one under Settings, Connected apps, then allow again. |
| `CLOSED` | A library proposal that is closed or expired is applied or rejected. | Create a new proposal. |
| `ITEM_DECIDED` | A selected item of a library proposal was already applied, rejected or marked stale. | Read the proposal again and select only pending items. |
| `PREVIEW_PENDING` | A `thumb` or `preview` signed URL is asked for while the preview is still being rendered. | Try again shortly. |
| `PREVIEW_FAILED` | No preview could be rendered for the file. | Use the `original` variant. |
| `NO_PREVIEW` | The file's type has no preview, or the file embeds none. | Use the `original` variant. |
| `PLAYBACK_PENDING` | A `playback` signed URL is asked for while the video's playback rendition is still being rendered. | Try again shortly, or use `original`. |
| `PLAYBACK_FAILED` | No playback rendition could be rendered for the video. | Use the `original` variant. |
| `NO_PLAYBACK` | The file needs no playback rendition: the original plays as it is, or it is not a video. | Use the `original` variant. |

`CONFLICT` without a reason (`details` is `null`):

| Message | When | What to do |
| --- | --- | --- |
| "another account uses this email address" | An email change is confirmed after another account took the address. The link stays usable. | Change to another address. |
| "this address belongs to a member of the organization" | An address that already belongs to a member is invited. | Nothing to do: they are already a member. |
| "you are already a member of this organization" | An invitation is accepted by someone who is already a member. The link stays usable. | Nothing to do. |
| "an export just finished; request again" | An export was requested at the moment the pending one finished. | Request the export again. |

### `SOLE_OWNER` (409)

- Message: "Transfer ownership or delete the organization first".
- `details.organizationIDs` lists the live organizations that would be left
  without an owner.
- Answered when the only owner leaves, is removed or is demoted, or deletes
  their account.
- What to do: make someone else an owner first, or delete the organization.

### `PAYLOAD_TOO_LARGE` (413)

| When | `details` | What to do |
| --- | --- | --- |
| An upload declares more bytes than the upload limit. | `limitBytes` | Upload a smaller file. |
| A ZIP download would hold more bytes than the archive limit. | `limitBytes` | Download fewer files at once. |
| A JSON request body is over 3 MiB. | `null` | Send less in one request. |
| An image of a feedback report is over 5 MiB, or the report's body is over its own limit. | `limitBytes` | Send a smaller image, or fewer. See [Giving feedback](../accounts/feedback.md#limits). |
| A crash report's body is over 64 KiB. | `limitBytes` | Send shorter fields. See [Crash reports](../accounts/crash-reports.md#limits). |
| An MCP tool's answer is over 8 MiB. The message reads "The answer is larger than MCP returns; read it over REST". | `null` | Ask for a smaller page (`limit`), or use REST. |

### `UNSUPPORTED_MEDIA_TYPE` (415)

- An upload's file extension is outside the list of accepted types, or its
  `contentType` does not match the extension.
- A request with a JSON body did not send `Content-Type: application/json`.
- An image of a feedback report is not a PNG, JPEG, WebP or GIF, judged by
  its bytes. See [Giving feedback](../accounts/feedback.md).
- What to do: see [Uploading](../files/uploading.md) for the accepted types.

### `RANGE_NOT_SATISFIABLE` (416)

- Message: "The requested range is not satisfiable".
- `details.sizeBytes` and `Content-Range: bytes */<size>` give the content's
  size.
- Answered when a `Range` request for a file's bytes starts past the end.

### `RATE_LIMITED` (429)

- Message: "Too many attempts; try again later".
- `details.retryAfterSeconds` and the `Retry-After` header give the whole
  seconds until the window ends. They are always at least 1.
- What to do: wait that long, then retry. Do not retry sooner: refused
  attempts do not extend the window, but they are not served either.
- What is limited, and to how much: [Limits](limits.md#rates).

### `INTERNAL` (500)

- Message: "Internal server error". `details` is always `null`.
- Something failed on our side. The cause is never in the answer.
- What to do: retry once. If it persists, report the `requestID`.
- A failed MCP tool call whose answer was not JSON reads "The operation
  answered <status>" under this code.

### `UNAVAILABLE` (503)

Message: "Temporarily unavailable; try again shortly".

| `details.reason` | When | What to do |
| --- | --- | --- |
| `UPLOADS_DISABLED` | New uploads are switched off. | Try again later. Existing files still read. |
| `EMAIL_UNAVAILABLE` | The request needs to send an email and email cannot be sent right now. | Try again later. |
| `IMAGE_SERVICE_UNAVAILABLE` | An image variant was requested while the image service is busy or down, or while the API is already sending as many originals to it as it holds at once. `Retry-After` gives the seconds to wait, at least 1. | Retry after that time. |
| `IMAGE_RENDER_TIMED_OUT` | Decoding and resizing an image variant took longer than 15 seconds. `Retry-After` gives the seconds to wait: 30. | Retry after that time. If it keeps failing, ask for a smaller width. |
| `STORAGE_CONTENDED` | Storing content collided with a concurrent removal of the same content three times in a row. | Retry the request. |

### `TIMEOUT` (503)

- Message: "The request did not finish in time; try again".
- A request has 30 seconds. A step inside the request that runs past its own
  time limit answers the same code.
- What to do: retry. A create that takes a `requestID` is safe to retry with
  the same `requestID`. A change that takes `expectedLockVersion` is safe to
  retry too: if the first attempt went through, the retry answers
  `STALE_LOCK_VERSION`.

## Refused uploads

An upload that fails verification is not an HTTP error. The upload's `state`
becomes `rejected` and its `rejectReason` says why:

| `rejectReason` | Meaning | What to do |
| --- | --- | --- |
| `OBJECT_MISSING` | Nothing was staged. | Start again and PUT the bytes. |
| `SIZE_MISMATCH` | The bytes are not the declared `sizeBytes`. | Declare the exact size. |
| `DIGEST_MISMATCH` | The bytes do not have the declared `sha256`. | Declare the right digest, or none. |
| `TYPE_NOT_ALLOWED` | The bytes are of a type that is not accepted. | See the accepted types. |
| `TYPE_MISMATCH` | The bytes are of another type than the file name claims. | Give the file its real extension. |
| `MEDIA_INVALID` | The image, document or video does not decode within its limits. | Export the file again from its source. |
| `MALWARE` | The scan found malware. | Do not upload the file. |
| `STALE_FILE_VERSION` | The file being replaced got a newer version meanwhile. | Start again from the current version. |
| `IN_TRASH` | The file being replaced was trashed meanwhile. | Restore it, then start again. |
| `INGEST_FAILED` | Verification gave up. It may pass another time. | Upload again. |

## OAuth errors

The OAuth endpoints that connected apps use follow the OAuth standards instead
of the envelope. See [Connected apps](../agents/connected-apps.md).

### Errors shown to the person

When the app itself cannot be trusted, nothing is sent to it. The browser goes
to `/connect?error=<error>`, which shows "This app cannot connect" and "Nothing
was shared with it."

| `error` | Text shown | When |
| --- | --- | --- |
| `invalid_request` | "The app's request is incomplete." | The request has no `client_id`. |
| `unauthorized_client` | "Talewright does not accept this app yet." | The app's client ID is not one Talewright accepts. |
| `invalid_client` | "The app's description could not be read, or does not describe it." | The app's client metadata document could not be fetched or is not valid. |
| `invalid_redirect_uri` | "The app asked to return somewhere its description does not list." | The `redirect_uri` is missing, not `https` or loopback `http`, or not listed in the app's document. |

A consent request that is older than 10 minutes, already answered, unknown,
or first opened by another account shows "This request has ended". Through
the API each of these answers `404 NOT_FOUND`, the same for all.

### Errors sent back to the app

Once the app and its redirect are trusted, errors go to the app's
`redirect_uri` as query parameters `error`, `state` and `iss`.

| `error` | When |
| --- | --- |
| `invalid_request` | A parameter is given twice. `state` is longer than 500 characters (it is then not sent back). `code_challenge` is missing or not 43 base64url characters. `code_challenge_method` is not `S256`. |
| `unsupported_response_type` | `response_type` is not `code`. |
| `invalid_target` | `resource` is missing or is not the MCP endpoint. |
| `invalid_scope` | `scope` names a scope that does not exist. |
| `access_denied` | The person chose "Deny". |

### Token endpoint errors

`POST /oauth/token` and `POST /oauth/revoke` answer JSON
`{"error": "...", "error_description": "..."}` with `Cache-Control: no-store`.

| `error` | HTTP status | `error_description` values |
| --- | --- | --- |
| `invalid_request` | 400 | "The body must be application/x-www-form-urlencoded"; "The body is too large" (over 16 KiB); "The body is not UTF-8"; "A parameter is repeated"; "grant_type is required"; "code is required"; "redirect_uri is required"; "code_verifier is required"; "refresh_token is required"; "code_verifier must be 43 to 128 unreserved characters"; "token and client_id are required" (revocation) |
| `invalid_client` | 401, with `WWW-Authenticate: Bearer error="invalid_client"` | "client_id is required"; "Clients are public: send client_id and no secret" (an `Authorization` header or a `client_secret` was sent) |
| `invalid_grant` | 400 | "The code is unknown, used or expired"; "The code was issued to another client"; "redirect_uri differs from the authorization request's"; "code_verifier does not match the code_challenge"; "The authorization ended during its exchange"; "The member is gone"; "The member no longer reaches what they granted"; "The member may no longer grant approval scopes"; "The member has the most connections to this app the organization allows" (10 working ones); "The refresh token is unknown, spent or expired"; "The refresh token was issued to another client"; "The refresh token was already used; the grant is revoked" |
| `invalid_scope` | 400 | "A refresh cannot change the scopes: omit scope or repeat the granted scopes exactly" (a refresh asked for other scopes than the connected app holds, fewer ones included) |
| `invalid_target` | 400 | "resource must be this server's MCP endpoint" |
| `unsupported_grant_type` | 400 | "Only authorization_code and refresh_token are supported" |
| `server_error` | 500 | "The token could not be issued" |

- Every `/oauth/` endpoint counts requests per client address. Past the limit
  it answers `429 RATE_LIMITED` in the ordinary envelope with `Retry-After`.
- `POST /oauth/revoke` answers `200` for any token, known or not.

## MCP errors

An agent connected over MCP sees three kinds of failure. See
[MCP](../agents/mcp.md#errors).

| Kind | What the agent sees |
| --- | --- |
| A tool ran and failed | A normal tool result with `isError: true`. Its `structuredContent` is the error envelope above, and its text content is the same JSON. Every code and reason on this page can appear here. |
| The request never reached a tool | An HTTP error with the envelope: `401 UNAUTHENTICATED` (no or bad token), `403 FORBIDDEN` (an `Origin` that is not allowed), `405 METHOD_NOT_ALLOWED` (not a `POST`), `429 RATE_LIMITED`. |
| The MCP request itself is wrong | A JSON-RPC error. |

JSON-RPC errors:

| Code | When |
| --- | --- |
| `-32602` | An unknown tool, or a tool whose scope the credential does not hold ("Unknown tool: <name>"). An invalid list cursor ("Invalid cursor"). A resource URI that is unknown or outside the credential's reach. A request in the `2026-07-28` style without its client capabilities. |
| `-32601` | A method the server does not serve, such as `prompts/list` or `completion/complete`. |
| `-32022` | A `2026-07-28` style request that names a protocol version the server does not support. The answer lists the supported ones. HTTP status 400. |
| `-32020` | A request whose `Mcp-Method` header disagrees with its body. HTTP status 400. |

- A failed resource read carries the error envelope as the JSON-RPC error's
  `data`.
- A tool called with an argument it does not take, or without a required
  argument, answers `isError` `VALIDATION_FAILED` with `details.field` before
  any request runs.

## Errors on the files host

File bytes are served from a separate host. Its refusals use the same envelope
and are never cached.

| Status | When |
| --- | --- |
| 403 | A signed URL or a ZIP download URL is malformed, expired or was stopped because the file was trashed or restored. |
| 404 | A public link's file is restricted, trashed, blocked by its status or unknown. All look the same. |
| 416 `RANGE_NOT_SATISFIABLE` | A byte range starts past the end. |
| 422 `VALIDATION_FAILED` | An image variant cannot be made. Seven messages: "Image addresses have no query", "Source must be a file delivery path", "Invalid image options" (`details.field` is `options`; `image` for the others), "Image source exceeds 64 MiB", "Image source exceeds 16,384 pixels a side or 100 million pixels", "The image source cannot be decoded" and "The resulting image is too large". [Image delivery](../files/image-delivery.md#errors) says when each is answered. |
| 503 `UNAVAILABLE` `IMAGE_SERVICE_UNAVAILABLE` | The image service is busy or down. `Retry-After` gives the seconds to wait. |
| 503 `UNAVAILABLE` `IMAGE_RENDER_TIMED_OUT` | Decoding and resizing an image variant took longer than 15 seconds. `Retry-After` gives the seconds to wait. |

## Questions and answers

**Which field do I branch on?**
`error.code` first, then `error.details.reason` when the code has reasons.
Never on `message` and never on the HTTP status alone: four codes share 409 and
two share 503.

**Why do I get `404` for something I know exists?**
Because you cannot reach it with what you presented. A workspace outside a
credential's list, a file in another organization and an unknown ID answer the
same `404`.

**Why `403 SESSION_REQUIRED` although my key has every scope?**
Scopes do not open browser-only operations. Managing credentials, members,
sharing and permanent deletion need a person signed in with a browser.

**What is the difference between `SESSION_REQUIRED` and
`HUMAN_APPROVAL_REQUIRED`?**
Both mean a bearer token cannot do this. `HUMAN_APPROVAL_REQUIRED` is the
answer for applying a library proposal: the step where a person reviews what
an agent prepared. Everything else browser-only answers `SESSION_REQUIRED`.

**What is the difference between `STALE_FILE_VERSION` and
`STALE_LOCK_VERSION`?**
`STALE_FILE_VERSION` is about bytes: someone uploaded a newer version.
`STALE_LOCK_VERSION` is about details: someone renamed, moved, tagged or
otherwise changed the file or folder.

**Is `TOKEN_INVALID` about my API key?**
No. It is about emailed links. A bad API key is `UNAUTHENTICATED` with reason
`INVALID_TOKEN`.

**Can I retry after `TIMEOUT` or `INTERNAL`?**
Yes. Creates that take a `requestID` and changes that take
`expectedLockVersion` are safe to repeat.

**How long do I wait after `RATE_LIMITED`?**
Exactly `details.retryAfterSeconds`, which equals the `Retry-After` header.

**Does a wrong password ever answer `401` inside the app?**
No. Only sign-in answers `INVALID_CREDENTIALS`. A wrong `currentPassword`
answers `422 VALIDATION_FAILED` on `currentPassword`, and after too many of
them `429 RATE_LIMITED`.

**Why does a batch fail for one file?**
Batches are all or nothing. One trashed file refuses the whole batch with
`IN_TRASH`, and one unknown file with `NOT_FOUND`.

**Where do I find the request ID?**
In the `requestID` property of the error body and in the `x-request-id`
response header of every response, successful ones included.

**Does an error ever contain a secret?**
No. Messages and details hold IDs, counts, field names and reasons. They never
hold tokens, passwords, signed URLs or file content.

## Related pages

- [The REST API](../agents/rest-api.md)
- [MCP](../agents/mcp.md)
- [Connected apps](../agents/connected-apps.md)
- [Limits](limits.md)
- [Roles and permissions](permissions.md)

