Docs menu

Errors and rate limits

The error format, every status the API sends, and how many requests each plan can make a minute.

The error format

Every answer is JSON and carries error. It is 0 when the call worked. When it did not, error is 1 and message says what went wrong in plain words:

JSON
{
  "error": 1,
  "message": "Link does not exist."
}

Show or log message. Do not match on its exact wording, because it can be improved. Match on the HTTP status.

Statuses

StatusMeaningWhat to do
200, 201, 204It worked.Read the body, except on 204.
400A value is not allowed. message says which one.Fix the request. Do not repeat it unchanged.
401The key is missing, wrong or belongs to a closed account.Send Authorization: Bearer YOUR_KEY.
403The plan does not include this, or a required password is wrong.Check the plan table, or the message.
404The link or click does not exist, or belongs to someone else. Both look the same on purpose.Check the id.
422A conversion field is not valid, or the click is too old to count.Fix the field named in message.
429More requests in a minute than the plan allows.Wait for the seconds in the Retry-After header.
501The path exists but that part of the API is not ready.See the not available page.

Rate limits

Each account can make a number of API requests a minute, set by its plan. All keys and requests of an account count together. The count is a rolling minute.

PlanRequests a minuteAPI accessLinks a monthRaw clicks kept
Free60Read and change500365 days
Pro120Read and change5,0001,095 days
Team300Read and change25,0003,650 days
Business600Read and change100,000No limit
Organization1,200Read and changeAgreed per customerNo limit

Every answer tells you where you stand:

  • X-RateLimit-Limit: the requests a minute the plan allows.
  • X-RateLimit-Remaining: how many are left in the current minute.
  • Retry-After: on a 429 answer only, the seconds to wait before trying again.

When you get a 429, wait for Retry-After and then continue. Do not retry in a tight loop. If you need more than your plan allows, upgrade or contact us.

The browser conversion call has its own limit of 60 requests a minute for each address. The AI assistant connector is limited per account by the same plan number, in a count of its own, so an assistant does not use up your API requests. See (https://siz.la/docs/connector).

Plan features at a glance

Options that need a feature your plan does not include are refused with a 400 or 403 and a message that says so.

FeatureFreeProTeamBusinessOrganization
Password on a linkYesYesYesYesYes
Expiry dateYesYesYesYesYes
Click limitYesYesYesYesYes
Targeting by country, device and languageYesYesYesYesYes
App deep linksYesYesYesYesYes
CampaignsNoYesYesYesYes
ConversionsNoYesYesYesYes
WebhooksNoYesYesYesYes
Raw click exportNoYesYesYesYes

Questions

What are the siz.la API rate limits?

Requests a minute by plan: Free 60, Pro 120, Team 300, Business 600. The limit is counted for the whole account over a rolling minute.

What does a 429 answer from the siz.la API mean?

You made more requests in a minute than your plan allows. Wait for the number of seconds in the Retry-After header, then continue.