BitlyDeveloper
Start Now

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.

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.

What's the API_USAGE_LIMIT_EXCEEDED error?

Each plan has a monthly limit on the number of API requests that can be made. If you get the ‘API_USAGE_LIMIT_EXCEEDED’ 429 response, it means your account has reached the maximum number of API requests it can make in a month.

To see your monthly limits, check our pricing page or look in the Billing and usage tab in your Account settings. If you have an Enterprise or custom plan, please consult your contract or contact your account manager for your plan's details.

Monthly limits reset on the first of the month. To increase your plan limits or access unavailable features, subscribe to a higher plan or contact your account manager for assistance.

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.

  • 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]-[DD]T[HH]:[MM]:[SS]±hhmm. For example: 2006-01-02T15:04:05-0700. When passing timestamps as a parameter, be sure they are URL encoded (i.e. replace '+' with '%2B' and ':' with '%3A') so that a unit_reference param value would look like unit_reference=2006-01-02T15%3A04%3A05-0700

Caching

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

Redirecting links

To redirect a link, send a PATCH request to the /v4/custom_bitlinks/{custom_bitlink} endpoint. PATCH /v4/bitlinks/{bitlink} cannot be used to update a link’s destination URL (i.e. redirect the link).

First, create a new short link to the new destination URL. Do this via the API with POST /v4/shorten or manually in the Bitly web app. Note that the domain for the new short link needs to match the existing link, whether it’s bit.ly or a custom domain.

Then, send a PATCH request to /v4/custom_bitlinks/{custom_bitlink}. This assigns the long URL from the new short link to the existing one that you want to redirect. Include this information:

  • bitlink_id — the short link that goes to the correct destination URL
  • custom_bitlink — the existing short link that you’re redirecting to the new destination