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.
| Header | Meaning |
|---|---|
X-RateLimit-Limit | The allowance for this request's group. |
X-RateLimit-Remaining | Requests remaining in that group's current window. |
X-RateLimit-Reset | The window's reset time as a Unix timestamp. Included on throttled responses. |
Retry-After | Seconds 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, or422until the request or account state changes. - For temporary
429responses, honorRetry-Afterwhen present. Stop retrying monthly allowance errors until the allowance changes. - Retry
500–503responses 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.