bitly API Best Practices
Please follow these guidelines when using the bitly API
bitly currently institutes per-hour, per-minute, and per-IP rate limits for each API method, and limits API users to a maximum of five concurrent connections from a single IP address. Our default limits are more than sufficient for nearly all use cases. Please read through this documentation in its entirety to avoid common causes of rate limiting issues.
Since bitly links never change or expire, we ask that you cache data locally wherever possible.
Avoiding API Calls on Page Loads
Most rate limiting issues are caused by extraneous API calls. We ask that you avoid making calls to the bitly API on page loads, and instead make these calls based on explicit user actions (such as clicking a “share” button).
Authenticating End-Users With OAuth 2
If you are shortening URLs on behalf of end-users, we ask that you use our OAuth 2 implementation to authenticate end-users before shortening. URLs shortened in this manner will be added to the specified end-user’s history, allowing the end-user to manage and track his/her shortened URLs. To register an OAuth application, see the page on authentication.
OAuth Token / API Key Security
OAuth access tokens (and API keys) should be treated as secret data and not exposed to users. To ensure the security of your OAuth access token or API key, we strongly suggest that you make requests to the bitly API server-side whenever possible.
If you have any specific questions about API key and access token security, please don't hesitate to contact us at email@example.com.
Custom Short Domains
When shortening a link with an access token for another user, we recommend that you do not set the
domain parameter. With no
domain parameter, the default is based on the user's preference.
Only specify the domain if the user has the opportunity to pick a valid domain from their
domain_preference_options, accessible via the user info endpoint.
HTTP Response Status Codes
Please note that all valid responses in json and xml format will carry an HTTP Response Status Code of 200. This means that invalid, malformed or rate-limited json and xml requests may still return an HTTP response status code of 200. In json and xml responses, the
status_txt values indicate whether a request is well formed and valid. For txt format calls, the HTTP Response Status Codes 403, 500 and 503 are used denote rate limiting, a problem with the request format, or an unknown error.
Checking for Errors
http://bit.ly/undefined -- if you are seeing such links, please check the
status_txt values for errors.
The bitly API does not support shortening more than one long URL with a single API call. However, up to 15 URLs can be handled in one API call using the
High-Volume Shorten Requests
If you need to shorten a large number of URLs at once, we recommend that you leave ample time to spread these requests out over many hours. Our API rate limits reset hourly. To inquire about high-volume use, please contact our sales team.
All long URLs sent to the bitly API must be URL encoded, even if these links already contain escaped characters. For more information about URL encoding, see this Wikipedia article.
For example, the link
should be fully escaped to
And the link
should be fully escaped to
A valid API call to shorten the link
http://example.com/page?parameter=value#anchor would be: