Troubleshooting & Tips

Most of the API issues you could encounter can be avoided by following two general guidelines:

  • Call POST /v4/shorten instead of POST /v4/bitlinks to 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 /v4/shorten.

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.

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.

  • We strongly suggest that you make requests to the Bitly API server-side whenever possible. Any requests to the Bitly API made via client-side JavaScript present the risk of your OAuth token being compromised. It is possible to partially obfuscate the token, but anything sent to the browser can be read by a determined user.
  • Never include your access_token inline in the page. Keep any references to your access_token in code that is contained in external javascript files which are included in the page.
  • Don't have the token itself contained anywhere in your JavaScript code, but rather make an ajax call to load it, and keep it in a variable stored in a privately scoped method.

URL Encoding

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: [YYYY]-[MM]-[DD]T[HH]:[MM]:[SS]±hhmm. For example: 2006-01-02T15:04:05-0700.


Since Bitly links never change or expire, we ask that you cache data locally wherever possible.