Search results for "{{ search.query }}"

No results found for "{{search.query}}". 
View All Results

Error Codes & Solutions

The Box API communicates errors through standard HTTP status codes with details supplied in JSON objects.

Generally the following pattern applies:

  • 2xx - Box received, understood, and accepted a request.
  • 3xx - The client must take further action in order to complete the request.
  • 4xx - An error occurred in handling the request. The most common cause of this error is an invalid parameter.
  • 5xx- Box received and accepted the request, but an error occurred while handling it.

If you have a suggested solution, please submit a suggested edit using the button on the top right of this page.

400 Bad Request

Error
Message
Solution

bad_digest

The specified Content-MD5 did not match what we received

While uploading a file, a Content-MD5 header with the SHA-1 hash of the file can be supplied to ensure that the file is not corrupted in transit. The SHA-1 hash that was supplied in the request did not match what was received in the upload. Supply a valid SHA-1 hash of the uploaded file.

bad_request

Required parameters supplied in the API request are either missing or invalid. Check the extended error message in the response body for more details.

cannot_make_collaborated_subfolder_private

Cannot move a collaborated subfolder to a private folder unless the new owner is explicitly specified

Specify the ID of the user that the content should be transferred to by setting the owned_by.id field in the request.

collaborations_not_available_on_root_folder

Root folder cannot be collaborated

You cannot set collaborators on a user's root folder (folder ID 0). Use a different folder ID than the root folder.

cyclical_folder_structure

Folder move creates cyclical folder structure

The folder ID specified in the folder move would create a cyclical folder structure (e.g. moving a folder to a sub-folder within itself). Change the folder ID for the folder move request.

folder_not_empty

Cannot delete – folder not empty

Delete all content from the folder before attempting to delete it.

invalid_collaboration_item

Item type must be specified and set to 'folder'

The item.type field of the collaboration item should be set to folder.

invalid_grant

Verify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code.

The authorization code supplied in the API request is missing or no longer valid. Possible solutions are:

  • Verify that the access token is added correctly in the request.
  • If correctly set, the access token may have expired. Attempt to refresh the access token or fetch a new one.

invalid_grant

Current date time must be before the expiration date time listed in the 'exp' claim.

This error occurs when the Unix time on your local machine and the Box server are out of sync.

To fix this error, update the Unix time on your machine to match the Unix time from this site, then try the request again.

invalid_limit

Limit is not a valid number

Add a valid numeric value for the supplied limit value.

invalid_offset

Offset is not a valid number

Add a valid numeric value for the supplied offset value.

invalid_request_parameters

Invalid input parameteres in request

Invalid parameters were sent in the API request. Check the API reference documentation for the correct request parameters that should be supplied for the API operation.

invalid_status

You can change the status only if the collaboration is pending

The status of a collaboration can only be updated to accepted or rejected by the user specified in the accessible_by field when the current status is set to pending. More information is available here.

invalid_upload_session_id

The upload session ID provided in the URL is not of a valid format.

The session ID supplied when making a chunked upload API request was invalid. Use the same session ID from the session that was created.

item_name_invalid

Item name invalid

Verify that the file's name is valid. Box only supports file or folder names that are 255 characters or less. File names containing non-printable ascii, "/" or "\", names with leading or trailing spaces, and the special names “.” and “..” are also unsupported.

item_name_too_long

Item name too long

Shorten the length of the name that is being supplied for the item. The maximum length of a file or folder name in Box is 255 characters or less.

password_reset_required

User needs to reset password

The user has not yet completed account setup steps.

requested_page_out_of_range

Requested representation page out of range

The range header supplied does not fit within the size of the specified item. Adjust the bounds to fit within the size of the item and try again.

requested_preview_unavailable

Requested preview unavailable

The thumbnail size requested for the file is not valid. See the reference docs for the API operation for available format sizes.

sync_item_move_failure

Cannot move a synced item

The item is set to be synced by the Box sync clients and cannot be moved. A possible solution is to set the sync_state of the item to not_synced.

task_assignee_not_allowed

Assigner does not have sufficient privileges to assign task to assignee

The user who is attempting to assign the task does not have the appropriate permissions to do so. Adjust the user permissions to allow the assignment of tasks.

terms_of_service_required

User must accept custom terms of service before action can be taken

The admin of your Box account has set custom terms of service and the user has not logged in to accept the terms yet. The user will need to accept the terms of service, or the admin will have to disable them, in order to proceed. More information is available here.

user_already_collaborator

User is already a collaborator

The user that you are attempting to collaborate in on an item is already collaborated on that item. This request is not needed.

401 Unauthorized

Error
Message
Solution

unauthorized

Unauthorized

Authorization token is not authorized, check extended error message in body for more details.

403 Forbidden

Error
Message
Solution

access_denied_insufficient_permissions

Access denied – insufficient permission

This error is typically produced when scopes that are needed for the API operation were not enabled. See here for solution information.

access_denied_item_locked

Access denied – item locked

You are attempting to access a locked fitem without appropriate permissions to access it. Unlock the item first, then try to access it again.

access_from_location_blocked

You’re attempting to log in to Box from a location that has not been approved by your admin. Please talk to your admin to resolve this issue.

file_size_limit_exceeded

File size exceeds the folder owner’s file size limit

See here for maximum file size limits based on account type.

forbidden

Client does not have permission to upload to this session. Only the user who initiated the upload session may upload to it.

incorrect_shared_item_password

A password is required for the shared item, but it was either incorrect or not supplied.

storage_limit_exceeded

Account storage limit reached

The storage limit of the account has been reached. Either upgrade your account or permanently delete content to continue. Content that is simply moved to the trash will still count towards the account total until it is permanently deleted.

user_email_confirmation_required

User needs to complete email confirmation

The user has not yet completed steps for email confirmation.

404 Not Found

Error
Message
Solution

not_found

The resource could not be found. Check the extended error message in the response body for more details.

not_trashed

Item is not trashed

The item that is to be permanently deleted is not in the trash. Send the item to the trash first.

preview_cannot_be_generated

Preview cannot be generated

You are not able to generate a preview thumbnail for the specified file.

trashed

Item is trashed

The item that is to be accessed is in the trash and unavailable for modification. Move the item out of the trash and try again.

405 Method Not Allowed

Error
Message
Solution

method_not_allowed

Method Not Allowed

The HTTP method used for the API operation is not allowed. Check the API reference documentation for the HTTP verb needed for the API operation.

409 Conflict

Error
Message
Solution

conflict

A resource with this value already exists

This error may be produced when the resource to be created already exists. Check the extended error message in the response body for more details.

item_name_in_use

Item with the same name already exists

This error is produced when a resource with the same name already exists. Ensure that the resource name being added / modified is unique.

operation_blocked_temporary

The operation is blocked by another ongoing operation

This error is returned when trying to access a folder that is blocked by another folder operation, such as a move or copy. Try again at a later interval.

recent_similar_comment

A similar comment has been made recently

A similar comment was recently made, and the API has flagged it as a potential duplicate. Verify that the comment was indeed made, or modify the comment content and try again.

user_login_already_used

User with the specified login already exists

A user with the same email already exists. Either refer to the existing user or specify a different email.

410 Gone

Error
Message
Solution

session_expired

The upload session associated with the given upload session ID has expired and can no longer be accessed.

upload_failed

The upload session is in an unrecoverable failed state and cannot continue. This or other requests have resulted in the upload session reaching a bad state (e.g. parts overlapping).
Possible situations where this may arise:

  • Maximum number of parts has been exceeded
  • Overlapping parts have been uploaded

411 Length Required

Error
Message
Solution

length_required

Content-Length header was required, but not provided.

Supply a content-length header within your API request.

412 Precondition Failed

Error
Message
Solution

precondition_failed

The resource has been modified. Please retrieve the resource again and retry

Check the extended error message in the response body for more details.

sync_state_precondition_failed

The resource has been modified. Please retrieve the resource again and retry

Check the extended error message in the response body for more details.

413 Request Entity Too Large

Error
Message
Solution

request_entity_too_large

Request Entity too Large

This error is produced when the size of the upload is more than the allowed maximum. Check the extended error message in the response body for more details.

429 Too Many Requests

Error
Message
Solution

rate_limit_exceeded

Request rate limit exceeded, please try again later

The client is performing operations too quickly and has been rate limited. Client is advised to retry their request after the amount of time specified by the Retry-After header.

There are two rate limits to be aware of. There is a limit of 10 API calls per second per user. There is also a limit of 4 uploads per second per user.

To solve this error, consider these approaches:

  • Backing off when rate limits are hit using an exponential back off method.
  • Caching information when possible to reduce necessary calls.
  • Imposing throttling on calls made from the application to Box.

500 Internal Service Error

Error
Message
Solution

internal_server_error

Internal Server Error

Client should retry using exponential back-off strategy

502 Bad Gateway

Error
Message
Solution

bad_gateway

Client should retry using exponential back-off strategy

503 Unavailable

Error
Message
Solution

unavailable

Unavailable

Please check our API status page for information.

Related Resources

Error Codes & Solutions