Troubleshooting & Tips
Most of the API issues you could encounter can be avoided by following two general guidelines:
POST /v4/shorteninstead of
POST /v4/bitlinksto shorten links.
- Include a specific group and custom domain in your shorten calls. In general, it's best to be specific in all of your calls rather than rely on the API defaults.
Is the OAuth token connected to a user or an organization?
The OAuth token is created by an individual user and is tied to that user's ID. You can use their OAuth token for all their organization's calls as long as the user remains on that account.
If the user is removed from the account, any integrations tied to that token/user will break.
Understanding the Group-Custom Domain Connection
When a user creates a Bitly account, an organization and a group are created for that specific user--this group will be set as their default API group. When the user is added to another Bitly organization, such as their company's shared account, they will be assigned to additional groups.
Including the group_guid parameter in your calls will bypass the default group and prevent some of the following issues.
We should have more links available, why are we hitting our limits? Why aren't links being shortened with our custom domain?
If the user who created the OAuth token hasn't changed their default API group, your calls may be using the group they created before being assigned to the organization with higher limits and a custom domain.
To bypass the defaults and avoid issues with groups and domains, always include a specific group and custom domain in your calls.
To change the user's default group, sign in to Bitly, open the profile menu, select Settings, click Integrations, choose the default group and click Save changes.
What's the INVALID_ARG_DOMAIN error?
You'll see this error when a call is trying to shorten links with a group that doesn't have access to the specified domain.
Custom domains are assigned to groups. If a shorten call with a custom domain relies on the authorizing user's default group, and the domain can't be accessed from that group, the call will fail. By specifying a group in the group_guid parameter, you will ensure that the correct group and domain are referenced.
The best solution for this error is to specify the group_guid in the body of
Another possible solution is to change the authorizing user's default group to a group that includes the custom domain. To change the default group, sign in to Bitly, open the profile menu, select Settings, click Integrations, choose the default group and click Save changes.
What's the BRANDED_LINK_MONTHLY_LIMIT_EXCEEDED/MONTHLY_BSD_ENCODE_LIMIT_REACHED error?
You'll see this error when a call is trying to shorten links with a custom domain, but you've already shortened over the allowed limit for the month. You can see your monthly usage under your account settings. To access this, log into your Bitly account and click on your settings on the top right. Then click on Account Name, followed by Account details. On this tab you should be able to view your "Branded links" usage.
Before Adding a Custom Domain
Before adding a custom domain and attempting to shorten links with it, we recommend following this guide to ensure your domain is set-up for use. If your DNS settings are not configured properly, you may see an error returned on shorten calls.
OAuth Token Security
OAuth access tokens should be treated as secret data and not exposed to any users. Ensure the security of your OAuth access token by following these guidelines.
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.
The V4 API uses the following format for timestamps:
Since Bitly links never change or expire, we ask that you cache data locally wherever possible.