API errors & retries

Understand API status codes and when a failed request is safe to retry.

When a T.LY API request fails, read the HTTP status and the response message together. The status tells you the type of problem. The message usually tells you what to change.

Start with a request that shows headers

Send API tokens as Bearer tokens. T.LY still accepts api_token as a query parameter for older integrations, but headers keep tokens out of URLs and most access logs.

curl -i --request POST "https://api.t.ly/api/v1/link/shorten" \
  --header "Authorization: Bearer $TLY_API_TOKEN" \
  --header "Accept: application/json" \
  --header "Content-Type: application/json" \
  --data '{"long_url":"https://example.com"}'

How rate limits are counted

Authenticated rate limits apply per user and are shared across that user's API tokens. Creating short links has its own counter. All other documented endpoints, including listing links, bulk requests, analytics and QR codes, share one general counter. See the API reference for the current limits.

Monthly link allowances

Your team's plan has a separate monthly link allowance. It is shared across the team's members and links created in the app or through the API. Check your plan in Settings > Subscription. A monthly limit does not clear when the minute ends. Upgrade your plan or wait for the next calendar month.

Status codes you should handle

Status What it usually means What to do
400 The request could not be completed. Check the response message and destination, then retry once. Do not loop on the same request.
401 The token is missing, invalid, or not accepted for that action. Create a new token in Settings > API and send it as a Bearer token.
402 The current team needs an active subscription. Check the team's subscription and make sure the token owner has the correct current team selected.
403 The account is known, but its subscription, verification, plan, team, or permissions do not allow the action. Read the message before changing code. Confirm email verification, team access, subscription, and plan support.
404 The link, OneLink, domain, webhook, or other resource was not found for the current team. Check the identifier and current team. Do not assume a resource from another team is visible.
409 The requested action conflicts with the resource's current state, such as retrying a disabled webhook. Refresh the resource and resolve its state before retrying.
422 A field failed validation or a product rule rejected the request. Examples include a disallowed domain, an ending already in use, or invalid Smart URL settings. Use the errors object when present. Otherwise, fix the condition named in message.
429 A rate limit or monthly link allowance was reached. Read message. For throttling, honor Retry-After; for a monthly limit, upgrade or wait for the next calendar month.
500–503 T.LY or an upstream service could not complete an otherwise valid request. Retry with a short backoff. Stop after a few attempts and contact support if it continues.

Common response shapes

A single error usually returns a message:

{
  "message": "API key is not valid."
}

Field validation can also return an errors object:

{
  "message": "The given data was invalid.",
  "errors": {
    "long_url": ["The long url field is required."]
  }
}

Handle 429 responses

Read message before retrying a 429. For temporary throttling, wait at least the number of seconds in Retry-After. If the header is missing, use exponential backoff with jitter and stop after a few attempts. Coordinate workers that share the same user allowance, even when they use different tokens.

If message says the monthly link allowance was reached, stop retrying until the allowance changes. Waiting a minute will not resolve a monthly limit.

HeaderMeaning
X-RateLimit-LimitThe allowance for this request's group.
X-RateLimit-RemainingRequests remaining in that group's current window.
X-RateLimit-ResetThe window's reset time as a Unix timestamp. Included on throttled responses.
Retry-AfterSeconds to wait before retrying a throttled request.

These headers are readable by browser API clients. A monthly allowance error does not provide a short retry delay.

Retry safely

  • Do not retry 401, 402, 403, 404, or 422 until the request or account state changes.
  • For temporary 429 responses, honor Retry-After when present. Stop retrying monthly allowance errors until the allowance changes.
  • Retry 500–503 responses a small number of times with backoff and jitter.
  • Do not blindly retry a timed-out create request. Link creation is not guaranteed to be idempotent, so another attempt can create another short link.
  • Keep the successful response before starting the next job. Log the method, path, status, and message, but never the API token.

Related guides

Still stuck?

Send us a message or email [email protected] and we'll help you sort it out. To flag a suspicious link, use Report abuse.