Upload Errors

Updated Sep 25, 2026·3 min read

Every error from the upload API has the same JSON body, apart from a create request whose body is not valid JSON: statusCode, errorCode, message and sometimes details. Branch on errorCode, which is stable; message is written for people and may be reworded. Where the table says Retry, sending the same request again can succeed: wait for the Retry-After header's seconds when the answer has one, otherwise a few seconds. For the whole flow, see Upload a File.

{
  "statusCode": 409,
  "errorCode": "UPLOAD/OUT_OF_ORDER",
  "message": "This library takes the chunks in order. Send the first range in nextExpectedRanges.",
  "details": {
    "nextExpectedRanges": [
      "52428800-119999999"
    ]
  }
}

Error codes

errorCode	Status	What to do
`UPLOAD/ALREADY_COMPLETING`	409	The upload is finishing or finished, so it cannot be cancelled. To remove the file, use Delete File.
`UPLOAD/CHECKSUM_MISMATCH`	400	The piece arrived damaged (AWS S3, Azure Blob). Retry.
`UPLOAD/CHECKSUM_NOT_SUPPORTED`	400	SharePoint and Google Drive cannot check `Content-MD5`. Send the piece without it.
`UPLOAD/CHUNKS_IN_FLIGHT`	429	Too many pieces are arriving at once. Retry.
`UPLOAD/CONFLICT_BEHAVIOR_NOT_ALLOWED`	400	The library does not take this `conflictBehavior`. Use one in `details.allowed`.
`UPLOAD/DESTINATION_CHANGED`	409	The destination folder was deleted, moved or renamed during the upload (AWS S3, Azure Blob). Create a new upload.
`UPLOAD/EXPIRED`	410	The upload expired. Create a new upload.
`UPLOAD/FOLDER_PATH_BLOCKED`	409	Something that is not a folder has the name of a folder in `folderPath`, given in `details.name`. Choose another path.
`UPLOAD/FOLDER_PATH_NOT_SUPPORTED`	400	Google Drive does not take `folderPath`. Name the folder with `folderId`.
`UPLOAD/INVALID_DRIVE`	400	`driveId` is not a drive of this library. Check it.
`UPLOAD/INVALID_FOLDER_PATH`	400	A folder name in `folderPath` is not allowed, or `folderPath` came with `replaceFileId`. Fix the path.
`UPLOAD/INVALID_RANGE`	400	`Content-Range` or the body's length does not match the upload. Fix it as `message` says.
`UPLOAD/LENGTH_REQUIRED`	411	Send the piece with a `Content-Length` header.
`UPLOAD/LIBRARY_NOT_SUPPORTED`	400	Upload to AWS S3, Azure Blob, SharePoint or Google Drive.
`UPLOAD/NAME_CONFLICT`	409	A file of this name exists and `conflictBehavior` is `fail`. Choose another name or `conflictBehavior`. From the last piece (AWS S3, Azure Blob), the upload has ended: create a new one.
`UPLOAD/NAME_RESERVED`	409	Another open upload is writing this file; `details.uploadId` names it. Retry once it ends, or cancel it.
`UPLOAD/NOT_ACCEPTING_CHUNKS`	409	The upload was cancelled or ended by an error. Create a new upload.
`UPLOAD/NOT_FOUND`	404	No upload with this URL or id, or it ended more than about seven days ago. Check the URL or id.
`UPLOAD/OUT_OF_ORDER`	409	SharePoint and Google Drive take pieces in order. Retry with the first range in `details.nextExpectedRanges`.
`UPLOAD/PROVIDER_UPLOAD_LOST`	409	The storage no longer holds the pieces sent so far. Create a new upload.
`UPLOAD/REPLACE_INCOMPATIBLE`	400	A new version needs the same extension as the file it replaces. Fix the name.
`UPLOAD/REPLACE_TARGET_CHANGED`	409	The file being replaced was deleted, moved, renamed or overwritten during the upload (AWS S3, Azure Blob). Create a new upload.
`UPLOAD/REPLACE_TARGET_NOT_FOUND`	404	`replaceFileId` is not a file in this library. Check the id.
`UPLOAD/STORAGE_ACCESS_DENIED`	403	CloudFiles can no longer reach your storage. Reconnect the library, then create a new upload.
`UPLOAD/STORAGE_UNAVAILABLE`	503	The storage was busy. Retry.
`UPLOAD/TOO_LARGE`	413	The file is over 20 GB (`details.maxSize`).
`UPLOAD/TOO_MANY_OPEN_SESSIONS`	429	Your account has 50 open uploads. Retry after one finishes or you cancel one.
`UPLOAD/TOO_MANY_RESENT_BYTES`	409	The upload has received more than twice the file's size, counting resent pieces. Create a new upload.
`COMMON/VALIDATION_FAILED`	400	A field is missing, mistyped or unknown, or the library is not connected. `message` says which.
`COMMON/UNAUTHORIZED`	401	The API key belongs to a partner user whose account has partner access turned off.
`COMMON/FORBIDDEN`	403	The API key is missing or unknown, or your HubSpot plan does not include the API. Check the key.
`COMMON/NOT_FOUND`	404	Something the request names, such as `folderId`, does not exist.
`COMMON/UNEXPECTED`	500	Something failed on our side. Retry. If it keeps failing, contact support.

Cancel Upload

Download File