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:
{
"error": {
"code": "VALIDATION_FAILED",
"message": "name must not contain control characters",
"details": { "field": "name" }
},
"requestID": "01928f3e-7c1a-7d2b-9a41-3f0c2d9e8b17"
}
error.codeis one of the 20 codes below.error.messageis English text that is safe to show to a person.error.detailsis always present. It is an object, ornullwhen the code has nothing to add.requestIDidentifies the request. The same value is in thex-request-idresponse header. Quote it when you ask for help.- Some codes add a response header. The table says which.
- Every operation can answer
500 INTERNALand503 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_TOKENcarriesWWW-Authenticate: Bearer error="invalid_token".- A token that does not authenticate answers
INVALID_TOKENon 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
Authorizationheader, whatever it holds: nothing is authenticated and nothing is counted. A bearer token sent together with a session cookie still answersAMBIGUOUS_CREDENTIALSthere. - At
/mcp, a missing token carriesWWW-Authenticate: Bearer resource_metadata="<app origin>/.well-known/oauth-protected-resource/mcp", and an invalid one carrieserror="invalid_token"and the sameresource_metadata. - In the web app any
UNAUTHENTICATEDanswer 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_FAILEDoncurrentPassword.
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. |
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_SCOPEcarriesWWW-Authenticate: Bearer error="insufficient_scope", scope="<scope>".- Over MCP a missing scope does not answer
INSUFFICIENT_SCOPEfor a whole tool: the tool is simply not listed and calling it is an unknown-tool error.INSUFFICIENT_SCOPEstill 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:
404first, then403for the role, then422for validation. - What to do: check the ID and that the credential covers its workspace. Call
workspaces_list(orGET /v1/workspaces) to see what a credential reaches.
METHOD_NOT_ALLOWED (405)
- Message: "This method is not allowed on this path".
/mcpaccepts onlyPOSTand answers anything else withAllow: POST.
VALIDATION_FAILED (422)
details.fieldnames 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_FAILEDwithdetails: 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 toName. - 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
tagswhen it is set on a file or named in anadd_tagorremove_tagitem of a suggestion, onnamewhen a tag is renamed to it. - A full list answers on its own field, not on
name. A 51st status answers onstatuses("a file space has at most 50 statuses"), a 51st custom field onfields("a file space has at most 50 fields") and a 101st choice of a field onchoices("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
UNAUTHENTICATEDINVALID_TOKEN.
STALE_FILE_VERSION (409)
- Message: "This file changed since you opened it".
details.currentVersionIDis the file's current version.- Answered when an upload that replaces a file names a
baseVersionIDthat 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.currentLockVersionis the current lock version.- Answered when a change to a file or folder sends an
expectedLockVersionthat 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.
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.organizationIDslists 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. |
| A crash report's body is over 64 KiB. | limitBytes | Send shorter fields. See Crash reports. |
| 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
contentTypedoes 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.
- What to do: see Uploading for the accepted types.
RANGE_NOT_SATISFIABLE (416)
- Message: "The requested range is not satisfiable".
details.sizeBytesandContent-Range: bytes */<size>give the content's size.- Answered when a
Rangerequest for a file's bytes starts past the end.
RATE_LIMITED (429)
- Message: "Too many attempts; try again later".
details.retryAfterSecondsand theRetry-Afterheader 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.
INTERNAL (500)
- Message: "Internal server error".
detailsis alwaysnull. - 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
requestIDis safe to retry with the samerequestID. A change that takesexpectedLockVersionis safe to retry too: if the first attempt went through, the retry answersSTALE_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.
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 answers429 RATE_LIMITEDin the ordinary envelope withRetry-After. POST /oauth/revokeanswers200for any token, known or not.
MCP errors
An agent connected over MCP sees three kinds of failure. See MCP.
| 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
isErrorVALIDATION_FAILEDwithdetails.fieldbefore 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 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.