Talewright Docs Open the app

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

CodeHTTP statusdetailsHeadersMeaning
UNAUTHENTICATED401null, or reason: INVALID_TOKEN or AMBIGUOUS_CREDENTIALSWWW-Authenticate for INVALID_TOKENNo valid session or bearer token.
INVALID_CREDENTIALS401nullThe email or the password is wrong at sign-in.
FORBIDDEN403null, or reason: SESSION_REQUIRED, HUMAN_APPROVAL_REQUIRED, INSUFFICIENT_SCOPE (with requiredScopes) or MAKES_FILES_PUBLIC (with becomePublic)WWW-Authenticate for INSUFFICIENT_SCOPEYou are known, but may not do this.
EMAIL_NOT_VERIFIED403nullThe action needs a verified email address.
SIGNUP_CLOSED403nullSign-up is closed to this address.
NOT_FOUND404nullThe thing does not exist, or you cannot reach it.
METHOD_NOT_ALLOWED405nullAllowThe path exists but not with this HTTP method.
VALIDATION_FAILED422field, or nullThe request is malformed or a value breaks a rule.
TOKEN_INVALID400nullAn emailed link is unknown, expired, used or replaced.
STALE_FILE_VERSION409currentVersionIDThe file got a newer version since the one you based a replacement on.
STALE_LOCK_VERSION409currentLockVersionThe file or folder changed since you read it.
CONFLICT409null, or reason (21 values, below)The request conflicts with the current state.
SOLE_OWNER409organizationIDsThe action would leave an organization without an owner.
PAYLOAD_TOO_LARGE413limitBytes, or nullA body, a file or an answer is over a size limit.
UNSUPPORTED_MEDIA_TYPE415nullThe file type or the request's content type is not accepted.
RANGE_NOT_SATISFIABLE416sizeBytesContent-Range: bytes */<size>The requested byte range starts past the end of the content.
RATE_LIMITED429retryAfterSecondsRetry-AfterToo many attempts in the current time window.
INTERNAL500nullAn unexpected failure on our side.
UNAVAILABLE503reason (5 values, below)Retry-After for IMAGE_SERVICE_UNAVAILABLE and IMAGE_RENDER_TIMED_OUTSomething the request depends on is not available right now.
TIMEOUT503nullThe request ran past its time limit.

Code by code

UNAUTHENTICATED (401)

details.reasonMessageWhenWhat 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.reasonMessageWhenWhat 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_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:

Areadetails.field values
Listscursor, limit
Creates that can be repeatedrequestID
Accountsemail, password, newPassword, currentPassword, newEmail, fullName
Organizations and workspacesname, workspaceName, confirmName, workspaceIDs
Credentials and connected appsname, organizationID, workspaceIDs, scopes, expiresInDays, overlapHours
Filesname, altText, description, caption, tags, folderID, fields, fileIDs, field, status, root, trash
Foldersname, parentID
Statuses and fieldsname, statuses, fields, statusID, statusIDs, fieldIDs, choices, choiceIDs
UploadsfileName, sizeBytes, sha256, folderID, baseVersionID
Library proposalssummary, items, payload, rationale
FavoritesfavoriteIDs
Image deliveryoptions, 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.

CONFLICT (409)

details.reason names the conflict. Every reason:

details.reasonWhenWhat to do
NAME_TAKENA 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.
CYCLEA folder is moved into itself or into a folder below it.Choose another destination.
IN_TRASHA 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_TRASHA 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_PENDINGAn upload that is no longer pending is cancelled, or a cancelled upload is completed.Start a new upload if you still need one.
OBJECT_MISSINGAn upload is completed before its bytes arrived. The upload stays pending.PUT the bytes, then complete again.
EXPIREDAn upload is completed after it expired.Start a new upload.
DIFFERENT_TYPEA 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_REUSEDA 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_PUBLICA 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_CHANGEA 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_PUBLICA status change would leave the default status allowing public use.Keep the default status one that does not allow public use.
LAST_WORKSPACEThe organization's only live workspace is deleted.Create another workspace first, or delete the organization.
CONNECTION_LIMITAn 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.
CLOSEDA library proposal that is closed or expired is applied or rejected.Create a new proposal.
ITEM_DECIDEDA selected item of a library proposal was already applied, rejected or marked stale.Read the proposal again and select only pending items.
PREVIEW_PENDINGA thumb or preview signed URL is asked for while the preview is still being rendered.Try again shortly.
PREVIEW_FAILEDNo preview could be rendered for the file.Use the original variant.
NO_PREVIEWThe file's type has no preview, or the file embeds none.Use the original variant.
PLAYBACK_PENDINGA playback signed URL is asked for while the video's playback rendition is still being rendered.Try again shortly, or use original.
PLAYBACK_FAILEDNo playback rendition could be rendered for the video.Use the original variant.
NO_PLAYBACKThe 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):

MessageWhenWhat 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)

WhendetailsWhat to do
An upload declares more bytes than the upload limit.limitBytesUpload a smaller file.
A ZIP download would hold more bytes than the archive limit.limitBytesDownload fewer files at once.
A JSON request body is over 3 MiB.nullSend less in one request.
An image of a feedback report is over 5 MiB, or the report's body is over its own limit.limitBytesSend a smaller image, or fewer. See Giving feedback.
A crash report's body is over 64 KiB.limitBytesSend 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".nullAsk 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.
  • What to do: see Uploading 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.

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.reasonWhenWhat to do
UPLOADS_DISABLEDNew uploads are switched off.Try again later. Existing files still read.
EMAIL_UNAVAILABLEThe request needs to send an email and email cannot be sent right now.Try again later.
IMAGE_SERVICE_UNAVAILABLEAn 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_OUTDecoding 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_CONTENDEDStoring 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:

rejectReasonMeaningWhat to do
OBJECT_MISSINGNothing was staged.Start again and PUT the bytes.
SIZE_MISMATCHThe bytes are not the declared sizeBytes.Declare the exact size.
DIGEST_MISMATCHThe bytes do not have the declared sha256.Declare the right digest, or none.
TYPE_NOT_ALLOWEDThe bytes are of a type that is not accepted.See the accepted types.
TYPE_MISMATCHThe bytes are of another type than the file name claims.Give the file its real extension.
MEDIA_INVALIDThe image, document or video does not decode within its limits.Export the file again from its source.
MALWAREThe scan found malware.Do not upload the file.
STALE_FILE_VERSIONThe file being replaced got a newer version meanwhile.Start again from the current version.
IN_TRASHThe file being replaced was trashed meanwhile.Restore it, then start again.
INGEST_FAILEDVerification 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."

errorText shownWhen
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.

errorWhen
invalid_requestA 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_typeresponse_type is not code.
invalid_targetresource is missing or is not the MCP endpoint.
invalid_scopescope names a scope that does not exist.
access_deniedThe person chose "Deny".

Token endpoint errors

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

errorHTTP statuserror_description values
invalid_request400"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_client401, 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_grant400"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_scope400"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_target400"resource must be this server's MCP endpoint"
unsupported_grant_type400"Only authorization_code and refresh_token are supported"
server_error500"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.

KindWhat the agent sees
A tool ran and failedA 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 toolAn 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 wrongA JSON-RPC error.

JSON-RPC errors:

CodeWhen
-32602An 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.
-32601A method the server does not serve, such as prompts/list or completion/complete.
-32022A 2026-07-28 style request that names a protocol version the server does not support. The answer lists the supported ones. HTTP status 400.
-32020A 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.

StatusWhen
403A signed URL or a ZIP download URL is malformed, expired or was stopped because the file was trashed or restored.
404A public link's file is restricted, trashed, blocked by its status or unknown. All look the same.
416 RANGE_NOT_SATISFIABLEA byte range starts past the end.
422 VALIDATION_FAILEDAn 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_UNAVAILABLEThe image service is busy or down. Retry-After gives the seconds to wait.
503 UNAVAILABLE IMAGE_RENDER_TIMED_OUTDecoding 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.