Core API best practices

User authorization

Never handle user login and password information. All application authentication should be completed using the OAuth. Each offical SDK has an approved implementation of OAuth and you should use one of these in your app if possible.

Find out more about how to use OAuth in our handy OAuth guide.

Handling revoked access

Your app should take precautions in case of revoked access. Access tokens may be disabled by the user (from the account page), revoked by Dropbox administrators in cases of abuse, or simply expire over time.

In the case where a token is no longer authorized, the API will return an HTTP Error 401 Unauthorized response. The iOS SDK detects 401s for you and will call the sessionDidReceiveAuthorizationFailure: method on the session's delegate to notify you that the authorization was revoked. The Android, Python, Ruby, and Java SDKs will all raise an exception on server errors that you can catch and inspect. Re-authenticating is typically all that is necessary to regain access.


Case insensitivity

A common thing that trips up new developers is that the Dropbox "file system" is case-insensitive, meaning that A/B/c.txt is the same file as a/b/C.txt and is the same file as a/B/c.txt.

This has also caused problems for developers who store file metadata from users in embedded databases (such as SQLite). Postgres is another database that is case sensitive and will cause problems. Case insensitive collations should be used when storing Dropbox metadata in these databases. Alternatively, developers need to make sure their query operators are explicitly case insensitive.

Rate limiting

The API limits the amount of calls your app can make per user. The limits are high enough that any reasonable use of the APIs shouldn't come close to hitting them. Apps that hit the rate limits will receive a 503 error which uses the Retry-After header to indicate exactly when it's okay to start making requests again. If your app uses OAuth 2.0, the error will be a 429 instead. If you keep hitting these limits, contact our developer support team and we'll work with you.