BitlyDeveloper
Navigation

Troubleshooting & Tips

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

  • Call /v4/shorten instead of /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, include a specific group and custom domain in your calls.

To change the default group, sign in to Bitly, open the profile menu, select Profile Settings, click Default API Group, choose the default group and click Save.

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 API Group to a group that includes the custom domain. To do this, sign in to Bitly, open the profile menu, select Profile Settings, click Default API Group, choose the default group and click Save.

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.

Timestamps

The V4 API uses the following format for timestamps: 'YYYY-MM-DDTHH:MM:SS±hhmm'. For example: '2006-01-02T15:04:05-0700'.

Caching

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