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"}'

Status codes you should handle

Status	What it usually means	What to do
`400`	The request could not be completed, sometimes because an upstream shortening provider failed.	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`	The request was throttled.	Read the message, honor `Retry-After` when present, and reduce request concurrency.
`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

A 429 response means T.LY cannot accept the request right now. Read the response message before retrying. When Retry-After is present, wait for that period and add exponential backoff with jitter when multiple workers share a token.

Retry safely

Do not retry 401, 402, 403, 404, or 422 until the request or account state changes.
For 429 responses, honor Retry-After when present.
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.

If the same valid request keeps failing, contact support with the endpoint, timestamp and timezone, HTTP status, and response message. Remove tokens and private URLs first.

Related guides

API basics & SDKs

CLI (Homebrew + Chocolatey)

Need more help?

If you still have questions, contact [email protected] or use the contact form. For abuse or suspicious links, use Report Abuse. For feature requests, email [email protected].

Get Started for Free Contact Support API Docs Blog