Proper error handling is key to building a high quality application and great end user experience. This document describes error types, common scenarios, and recommendations to ensure your application follows best practices.
Conventions
The Dropbox API uses standard response codes to indicate error types, with JSON or plaintext bodies with detail. While this doc refers to HTTP codes, note that the Dropbox SDKs will tend to represent errors using a Dropbox exception base class and subclasses.
For a summary of error classes and JSON response bodies, refer to the Error section of the http reference docs. This guide provides additional detail on common causes, resolution, and best practices.
Causes and Resolutions
400 - Bad Request
A common cause of this is malformed JSON request bodies, or JSON that does not conform to input fields and validation. Neglecting to sanitize input from end users, for example, would result in this.
These errors may also occur from attempting to access an endpoint unavailable to a given app type. For example, a Business application with Team Member Management attempting to use an endpoint requiring Team Auditing permission.
Responses with 400 error code indicate an issue with the request itself, and thus will not be resolved by retrying them.
401 - Unauthorized
These errors are due to the bearer token of the associated request being invalid, expired, or lacking sufficient permission to perform the associated API call. These may also be due to temporary suspension, such as an administrator suspending a member within a Dropbox business team.
Note that Dropbox users may revoke API authorizations (as described here) - so this error may suggest the end user unlinking the app in Dropbox (but not uninstalling your app or unlinking through it).
With the exception of suspension, retrying a 401 will not succeed. If your application experiences a 401, it should prompt that user to re-authenticate. For more information, see our OAuth guide.
403 - Forbidden
A 403 indicates that the user or team does not have access to the corresponding call.
This may be due to a change in the users Dropbox plan. Functionality that is specific to paid Dropbox plans can be introspected with the /features/get_values API call.
This may also be due to some classes of pauses and limits on accounts. For example, Dropbox Business accounts may have monthly limits on upload calls - and exceeding them for the month will result in some calls returning 403’s.
A call that results in 403 may succeed on retry, but only after corresponding action on the account. This category of error is more likely (but not guaranteed) to have a user_message to relay.
For apps performing background operations, this error case should not be rapidly re-tried. An exponential backoff - pausing longer after each failure - is recommended.
409 - Conflict (Endpoint Specific Error)
Endpoint specific errors can have a variety of different causes - refer to the specific endpoint’s documentation to see error cases and how to handle them.
One of the more common causes for many of these categories of errors is path_not_found. Remember - users may move and delete content, or change the permissions of shared folder at any time through the Dropbox UI - so be sure to test against this behavior.
If your application needs to detect changes that occur within folders, refer to our Detecting Changes Guide.
429 - Rate Limit (Too Many Requests)
These errors suggest one of two things:
- Your application is making too many API calls in a short period of time, and is experiencing a rate limit from the Dropbox API.
- There are too many simultaneous writes to the same namespace in parallel. This is likely due to multiple threads/instances from your app writing to the same space, but on occasion may be due to user behavior outside your app.
Rate limit responses from the Dropbox API may include a Retry-After header, indicating how long your app should wait (in seconds) before retrying. If a Retry-After header is not returned, your app should pause briefly before retrying, ideally using an exponential backoff.
Seeing high rates of 429’s suggests your app should use batch endpoints and optimize for performance.
500 - Internal Server Error
Internal server errors are undefined errors on the Dropbox side. In general, the causes for 500 errors are expected to be brief. Visit https://status.dropbox.com/ or contact API support if you see this for an extended period of time.
For apps performing background operations, this error case should not be rapidly re-tried - use exponential backoff.
Best Practices
Use SDKs
When possible, use official Dropbox SDK’s when writing your applications. These SDKs all use the same underlying HTTP calls, but provider helper classes for input and error handling. Using these SDKs will help prevent bad requests.
Logging
Track your error rates. While some types of 4xx errors will occasionally occur as users interact with content, very high rates of errors relative to success may signal issues with your application.
All Dropbox API calls (whether successful or 4xx) return an X-Dropbox-Request-Id HTTP header in their responses. Should you need help from Dropbox developer support, referring to this value can help expedite troubleshooting - logging these may help you debug in the future.
Use Prefix Matching on Errors
When programmatically handling 4xx errors, do not use exact string matching on the error_summary field. Prefix matching on error_summary is acceptable, but the summary may contain additional detail appended to the end of the string, making it unsuitable for exact matching.
Test All Error Types
And of course, be sure to test against all of the major error types described above.
