Box Developer Documentation
 

    Errors

    Errors

    The Box APIs uses HTTP status codes to communicate if a request has been successfully processed or not.

    Client error

    Most client errors in the HTTP 4XX, and some server errors in the HTTP 5XX range returns a standard client error JSON object.

    {
      "type": "error",
      "status": 400,
      "code": "bad_digest",
      "help_url": "https://developer.box.com/guides/api-calls/permissions-and-errors/common-errors/",
      "message": "The specified content-md5 did not match what we received",
      "request_id": "abcdef123456"
    }
    

    See the Client Error resource for more details.

    Common error codes

    Check our Developer Troubleshooting Articles for solution to common errors encountered when working with the Box APIs.

    400 Bad Request

    Errorbad_digest
    MessageThe specified content-md5 did not match what we received.
    SolutionWhile 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.
    Errorbad_request
    Message
    SolutionRequired parameters supplied in the API request are either missing or invalid. Check the extended error message in the response body for more details.
    Errorcannot_make_collaborated_subfolder_private
    MessageCannot move a collaborated subfolder to a private folder unless the new owner is explicitly specified.
    SolutionSpecify the ID of the user that the content should be transferred to by setting the owned_by.id field in the request.
    Errorcollaborations_not_available_on_root_folder
    MessageRoot folder cannot be collaborated
    SolutionYou cannot set collaborators on a user's root folder (folder ID 0). Use a different folder ID than the root folder.
    Errorcyclical_folder_structure
    MessageFolder move creates cyclical folder structure
    SolutionThe folder ID specified in the folder move would create a cyclical folder structure (for example moving a folder to a subfolder within itself). Change the folder ID for the folder move request.
    Errorfolder_not_empty
    MessageCannot delete – folder not empty
    SolutionDelete all content from the folder before attempting to delete it.
    Errorinvalid_collaboration_item
    MessageItem type must be specified and set to 'folder'
    SolutionThe item.type field of the collaboration item should be set to folder.
    Errorinvalid_grant
    MessageVerify the authorization code is set correctly in your request, or your application likely needs to get a new authorization code.
    SolutionThe authorization code supplied in the API request is missing or no longer valid. Possible solutions are to 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.
    Errorinvalid_grant
    MessageCurrent date time must be before the expiration date time listed in the 'exp' claim.
    SolutionThis 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 a synchronized time server, then try the request again.
    Errorinvalid_limit
    MessageLimit is not a valid number
    SolutionAdd a valid numeric value for the supplied limit value.
    Errorinvalid_offset
    MessageOffset is not a valid number
    SolutionAdd a valid numeric value for the supplied offset value.
    Errorinvalid_request_parameters
    MessageInvalid input parameters in request
    SolutionInvalid 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.
    Errorinvalid_status
    MessageYou can change the status only if the collaboration is pending
    SolutionThe 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.
    Errorinvalid_upload_session_id
    MessageThe upload session ID provided in the URL is not of a valid format.
    SolutionThe session ID supplied when making a chunked upload API request was invalid. Use the same session ID from the session that was created.
    Erroritem_name_invalid
    MessageItem name invalid
    SolutionVerify 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 characters, names containing the characters /, \, <, >, :, `
    Erroritem_name_too_long
    MessageItem name too long
    SolutionShorten 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.
    Errormetadata_after_file_contents
    MessageMetadata is included after file contents in a file upload request.
    SolutionInclude the file metadata before the file's contents.
    Errorpassword_reset_required
    MessageUser needs to reset password
    SolutionThe user has not yet completed account setup steps.
    Errorrequested_page_out_of_range
    MessageRequested representation page out of range
    SolutionThe 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.
    Errorrequested_preview_unavailable
    MessageRequested preview unavailable
    SolutionThe thumbnail size requested for the file is not valid. See the reference docs for the API operation for available format sizes.
    Errorsync_item_move_failure
    MessageCannot move a synced item
    SolutionThe 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.
    Errortask_assignee_not_allowed
    MessageAssigner does not have sufficient privileges to assign task to assignee
    SolutionThe 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.
    Errorterms_of_service_required
    MessageUser must accept custom terms of service before action can be taken
    SolutionThe 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.
    Erroruser_already_collaborator
    MessageUser is already a collaborator
    SolutionThe user that you are attempting to collaborate in on an item is already collaborated on that item. This request is not needed.

    401 Unauthorized

    Errorunauthorized
    MessageUnauthorized
    SolutionAuthorization token is not authorized, check extended error message in body for more details.

    403 Forbidden

    Erroraccess_denied_insufficient_permissions
    MessageAccess denied – insufficient permission
    SolutionThe Access Token does not have the appropriate user permissions or scopes. See here for solution information.
    Errorinsufficient_scope
    MessageThe request requires higher privileges than provided by the access token.
    SolutionThis error is typically produced when scopes that are needed for the API operation are not enabled. Check your configured application scopes and reauthorize your application, if applicable.
    Erroraccess_denied_item_locked
    MessageAccess denied – item locked
    SolutionYou are attempting to access a locked item without appropriate permissions to access it. Unlock the item first, then try to access it again.
    Erroraccess_from_location_blocked
    Message
    SolutionYou’re attempting to log in to Box from a location that has not been approved by your admin. Talk to your admin to resolve this issue.
    Errorfile_size_limit_exceeded
    MessageFile size exceeds the folder owner’s file size limit
    SolutionSee here for maximum file size limits based on account type.
    Errorforbidden
    Message
    SolutionClient does not have permission to upload to this session. Only the user who initiated the upload session may upload to it.
    Errorforbidden_by_policy
    MessageAccess denied – Blocked by Shield Access Policy
    SolutionShield access policies applied on your enterprise have prevented this action. Contact your enterprise admin to adjust the applied Shield access policies.
    Errorforbidden_by_policy
    MessageAccess denied – Blocked by Shield Malware Detection Rule
    SolutionAn active Shield malware detection rule prevents download or local editing of potentially malicious content, but preview and online editing remain available. Contact your enterprise admin to adjust the applied Shield policies.
    Errorincorrect_shared_item_password
    Message
    SolutionA password is required for the shared item, but it was either incorrect or not supplied.
    Errorstorage_limit_exceeded
    MessageAccount storage limit reached
    SolutionThe 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.
    Erroruser_email_confirmation_required
    MessageUser needs to complete email confirmation
    SolutionThe user has not yet completed steps for email confirmation.
    Errorcors_origin_not_whitelisted
    MessageAccess denied - Did you forget to safelist your origin in the CORS configuration of your app?
    SolutionYour application tried to access the Box API from a website. The application needs to explicitly allow Cross Origin Resource Sharing for the domain your site is hosted on.

    404 Not Found

    Errornot_found
    Message
    SolutionThe resource could not be found. Check the extended error message in the response body for more details.
    Errornot_trashed
    MessageItem is not trashed
    SolutionThe item that is to be permanently deleted is not in the trash. Send the item to the trash first.
    Errorpreview_cannot_be_generated
    MessagePreview cannot be generated
    SolutionYou are not able to generate a preview thumbnail for the specified file.
    Errortrashed
    MessageItem is trashed
    SolutionThe 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

    Errormethod_not_allowed
    MessageMethod Not Allowed
    SolutionThe 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

    Errorconflict
    MessageA resource with this value already exists
    SolutionThis error may be produced when the resource to be created already exists. Check the extended error message in the response body for more details.
    Erroritem_name_in_use
    MessageItem with the same name already exists
    SolutionThis error is produced when a resource with the same name already exists. Ensure that the resource name being added / modified is unique.
    Errorname_temporarily_reserved
    MessageThe item name is reserved by another processing item. Wait and then retry the request, or wait and check the parent folder to see if the name is in use.
    SolutionTwo duplicate requests have been submitted at the same time. Box acknowledges the first and reserves the name, but a second duplicate request arrives before the first request has completed. Allow the first request to complete before sending the second.
    Erroroperation_blocked_temporary
    MessageThe operation is blocked by another ongoing operation
    SolutionThis 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.
    Errorrecent_similar_comment
    MessageA similar comment has been made recently
    SolutionA 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.
    Erroruser_login_already_used
    MessageUser with the specified login already exists
    SolutionA user with the same email already exists. Either refer to the existing user or specify a different email.

    410 Gone

    Errorsession_expired
    Message
    SolutionThe upload session associated with the given upload session ID has expired and can no longer be accessed.
    Errorupload_failed
    Message
    SolutionThe upload session is in an unrecoverable state and cannot continue. This or other requests have resulted in the upload session reaching a bad state (for example parts overlapping). Possible situations where this may arise include when the maximum number of parts has been exceeded or when overlapping parts have been uploaded.

    411 Length Required

    Errorlength_required
    Messagecontent-length header was required, but not provided.
    SolutionSupply a content-length header within your API request.

    412 Precondition Failed

    Errorprecondition_failed
    MessageThe resource has been modified. Retrieve the resource again and retry
    SolutionCheck the extended error message in the response body for more details.
    Errorsync_state_precondition_failed
    MessageThe resource has been modified. Retrieve the resource again and retry
    SolutionCheck the extended error message in the response body for more details.

    413 Request Entity Too Large

    Errorrequest_entity_too_large
    MessageRequest Entity too Large
    SolutionThis error is produced when the size of the upload is more than the allowed maximum. Check the extended error message in the response body

    415 Unsupported Media Type

    Errorunsupported_media_type
    MessagePreviews for boxnote files are not yet supported.
    SolutionThis error is produced when requested an embed preview of a Box Note. Embedded previews are currently unsupported for Box Notes.

    429 Too Many requests

    Errorrate_limit_exceeded
    MessageRequest rate limit exceeded, try again later.
    SolutionThe 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 four rate limits to be aware of.

    500 Internal Service Error

    Errorinternal_server_error
    MessageInternal Server Error
    SolutionClient should retry using exponential back-off strategy

    502 Bad Gateway

    Errorbad_gateway
    Message
    SolutionClient should retry using exponential back-off strategy

    503 Unavailable

    Errorunavailable
    MessageUnavailable
    SolutionIf a Retry-After header is provided in the response, the client should retry the request according to the header value. In rare situations, a write operation may eventually persist its changes after the 503 response is received by the client, so the client should handle this case upon retry. If the issue persists, check our Status Site for any known outage information.