What went wrong, as a URL on the site: https://<site>/api/v1/problems/<slug>. Always present.
title
A short summary of the type. Always present.
status
The HTTP status. Always present.
code
The same condition as an upper-case code (PRECONDITION_FAILED), in the style Foldr’s other APIs use. Always present.
detail
More about this occurrence, where there’s something safe to say. May be absent or null.
instance
A fault code (# and 8 hexadecimal digits) for this occurrence, where there is one. Quote it to support if you ask for help.
operation
Present only on a problem that is how an operation ended: that operation as it stands.
Branch on type (or code) and the HTTP status. Never branch on title or detail, which are for people and can be reworded. New problem types can appear within v1, so keep a sensible default for an type you don’t know: handle it by its status class (a 4xx you can’t fix by retrying, a 503 you can).
The problem-type pages. Each type URL resolves, with no token, to a short page saying what the problem means and what to do about it. It’s HTML for a browser, and JSON if you ask with Accept: application/json (it adds a description member). An unknown slug is 404 not-found.
The API answers in problem documents everywhere, including a 401 for a missing token and a 429 from a rate limiter. The two exceptions are the OAuth endpoints (/oauth/token, /oauth/revoke, /oauth/register), which answer in OAuth’s own {"error": "..."} form (see Getting access), and the bare {"error":"not_found"} that a site with connected apps switched off gives for every address.
Headers that go with errors.Retry-After (seconds) accompanies every 429 and every 503, and most operations’ 202. WWW-Authenticate accompanies 401 invalid-token and 403 insufficient-scope. Allow accompanies 405.
The “what to do” column is advice for a client. “Nothing was changed” means what it says: where a refusal leaves a change undone, a client may treat the request as not made.
Sending it again unchanged will fail the same way.
Type
Meaning
What to do
invalid-request
The request couldn’t be read: malformed JSON, a body over 1 MB, a parameter given twice or as a list, a value of the wrong kind (a limit that isn’t a whole number, or 0), a missing or invalid Idempotency-Key, If-Match: * where a version has to be named, or If-Match on uploadFile.
Fix the request. The detail usually says which part.
invalid-path
The path isn’t a path inside the share (see Conventions), or a new name isn’t a single valid name. Nothing was looked up.
Fix the path or name.
invalid-cursor
The cursor isn’t one Foldr issued for this collection and query.
Use next_cursor exactly as returned, with the same other parameters.
copy-into-itself
A folder can’t be copied into itself or into a folder inside it.
Choose a destination outside it. Nothing was copied.
move-into-itself
A folder can’t be moved into itself or into a folder inside it.
Choose a destination outside it. Nothing was moved.
The access token is missing, expired, revoked, or not for this API. Every token failure is this one answer, with no reason, on purpose.
Refresh the token and try once more. If refreshing fails, send the person through sign-in again. The WWW-Authenticate header says where the authorisation server is described.
The token is valid but wasn’t granted the scope this operation needs. WWW-Authenticate names it.
Ask for the scope next time the person signs in (if the app’s policy allows it). Don’t loop.
write-not-allowed
The change isn’t allowed: the person may not make it there (no write permission, a file published as an approved version they may only read, a field they may not set, a kind of sharing they may not ask for), or the organisation doesn’t allow this app to make this kind of change.
Tell your user the change isn’t available to this app here. Retrying won’t help.
download-blocked
A label on the file stops it being downloaded (or, for a copy or move into another share, stops it leaving its share).
Tell your user. Retrying won’t help.
legal-hold
The item, a folder it’s in, or something inside the folder is under a legal hold. Nothing under a hold can be replaced, moved, renamed, restored over or deleted, by anyone, until the hold is released in Foldr.
Tell your user. Nothing was changed.
needs-approval-not-available
The organisation requires approval for this app’s changes, and replacing a file’s contents can’t be held for approval, so the app can’t replace files.
Don’t offer overwrite to this app’s user; use another route (the person can replace the file in Foldr). Deletes, moves and version restores are offered, each waiting for an approver.
change-declined
A change that was held for approval was declined by an approver. Nothing was changed.
Show it as declined. Ask again only if the person wants to. Seen when you poll the operation.
ai-content-blocked
Reserved: a label keeps the file away from AI tools. No v1 operation raises it today, because the API calls no AI model.
Handle it like download-blocked if you ever see it.
There’s nothing here the person can see: no such share, nothing at that path, no such field or operation. It’s the same answer whether the thing doesn’t exist or isn’t theirs.
Don’t try to tell the cases apart.
method-not-allowed
The address exists but doesn’t answer that method. Allow lists the methods it does.
Fix the method.
409: the thing is in a state that doesn’t allow this
Something with that name is already there, or the item already has that name. Nothing is ever replaced. Also: the name is being written right now, or a request with the same Idempotency-Key is still being handled.
Choose another name, or send on_conflict: "rename". For an in-progress request, wait and send it again.
not-a-folder
The path names a file where a folder was expected.
Fix the path.
not-a-file
The path names a folder where a file was expected.
Fix the path.
ambiguous-path
Two items in the folder have names that differ only in how their accented characters are encoded, so the path could mean either.
Take the exact path from a listing.
not-downloadable
A Google document type that can’t be downloaded (a Google Form). Its item’s export is null.
Open it in Google.
no-direct-download
The share doesn’t offer direct downloads.
Use getContent.
no-direct-upload
The share doesn’t take uploads straight to its storage.
Use uploadFile.
upload-incomplete
You completed an upload session but the storage doesn’t hold the declared file (nothing there, or not that many bytes). The session stays open.
Finish sending the file, then complete again; or cancel.
storage-account-not-connected
The share is in the person’s own cloud storage account (Google Drive, OneDrive, Dropbox, Box) and they haven’t yet given Foldr their sign-in to that service.
Ask the person to open the share in Foldr’s web app, or go to Me › Services, and connect the account. Then try again.
approved-version-unavailable
The file is published as an approved version, which is what this person is given, and that version can’t be read from storage. Asking again won’t help.
Someone who manages the share has to publish the file again.
no-approver
A share request, or a change that needs approval, would need someone other than the person to approve it, and there is nobody. Nothing was saved or changed.
An administrator has to name approvers for the share.
already-shared
The person already shares that item, or a request to share it is waiting. An app only starts sharing.
Leave it; changes to an existing share are made in Foldr.
copy-incomplete
A copy finished but some of the folder’s items couldn’t be copied. What was copied is left in place.
The operation’s failures list names what wasn’t copied. Copy those yourself, or remove the partial copy and ask again.
operation-cancelled
The operation was cancelled before it finished. Whatever a cancelled copy or move had made was removed, and a cancelled move’s original is where it was. A change held for approval that was withdrawn changed nothing.
Show it as cancelled.
operation-finished
You tried to cancel an operation that has already finished.
Read the operation for how it ended.
published
The file is published as an approved version (or the folder holds one). An app can’t move or delete a published file.
Someone who manages the share has to unpublish it in Foldr first.
envelope-source
The file is the document of a signing request still out for signature (or the folder holds one). An app can’t replace, move or delete it.
Wait until the signing is finished or cancelled.
folder-too-large
A folder has more than 1,000 files and folders, more than an app may move or delete in one request (or, for a move to another share, is nested more than 64 folders deep).
Move or delete the folders inside it separately. Nothing was changed.
not-recoverable-here
The share’s storage can’t undo this change and its administrator doesn’t let apps make changes there that can’t be undone.
Tell your user the change isn’t available to apps on this share. People can still make it in Foldr. Nothing was changed.
source-remains
A move to another share copied everything, and the copy is whole, but the original (or some of a folder’s items) couldn’t then be removed. It is now in both places. Nothing is lost.
Check the copy, then delete what’s left at the original place yourself. Moving it again would make a second copy.
change-expired
A change held for approval wasn’t decided in time (14 days unless the organisation says otherwise). Nothing was changed.
Ask again if it’s still wanted.
requester-not-connected
A change was approved, but the share couldn’t be opened as the person who asked (their own sign-in to the storage isn’t available now, or they can no longer reach the share). Nothing was changed.
If-Match didn’t name the item (or its field values) as it is now; or If-None-Match: * on an upload where the name is taken.
Read the item again and decide again. For an upload, choose another name or use on_conflict=rename.
changed-since-requested
412
A change held for approval was approved, but the item changed after you asked: the If-Match you sent no longer names it. Nothing was changed.
Read the item again and ask again if the change is still wanted.
too-large
413
There isn’t enough storage left in the share for that (a declared size over quota, or over a storage limit such as a Dropbox direct upload’s 150 MB).
Free space, or send less.
copy-too-large
413
A folder holds more files and folders than one copy takes (10,000) or is nested more than 64 folders deep.
Copy the folders inside it separately. Nothing was copied.
validation-failed
422
A value can’t be used as given: a field value that doesn’t suit the field, a recipient who can’t be found, a sharing term that isn’t allowed. Nothing was changed.
Fix the value.
idempotency-key-reused
422
This Idempotency-Key was used within 24 hours for a different request.
Use a new key for each new request; repeat a key only with the same request.
checked-out
423
Someone else has the item (or a file inside the folder) checked out in Foldr.
Try again later; it can be changed once they check it in.
precondition-required
428
The change needs an If-Match header (or, for uploadFile, If-None-Match: *).
Read the item, then send the change with its ETag.
Too many calls, too many uploads in flight (4 for each person through your app), or too many copies waiting (20).
Wait Retry-After seconds.
daily-write-limit
The app has reached its daily limit of changes for this person. Retry-After is the time until it resets at midnight UTC.
Stop making changes for that person until then.
destructive-budget
The app has used its daily allowance of replacements, moves and deletions for this person (counted in items; a folder counts everything in it), or this change alone would go past it. Nothing was changed.
Try again later. If it keeps happening, quote instance to support.
share-unreachable
503
The share’s file server couldn’t be reached just now.
Try again after Retry-After.
share-unavailable
503
The share couldn’t be opened just now.
Try again after Retry-After.
write-failed
503
The storage didn’t complete the change just now.
Read the item again before trying again: the change may or may not have been made. With an Idempotency-Key, sending the same request again is also safe.
copy-interrupted
503
A copy or move was stopped by the server more often than it’s restarted, or waited too long to start (a day).
Read the destination before asking again: part of it may have been copied. A move stopped while copying hasn’t touched the original.
The OpenAPI document lists, for each operation, every status it can answer and the problem types behind each. Any operation can also answer 400 invalid-request, 401 invalid-token, 403 insufficient-scope, 429 rate-limited and 500 internal-error; the document includes those for you.
