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:
{
"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
| Status | Meaning | What to do |
|---|---|---|
200, 201, 204 | It worked. | Read the body, except on 204. |
400 | A value is not allowed. message says which one. | Fix the request. Do not repeat it unchanged. |
401 | The key is missing, wrong or belongs to a closed account. | Send Authorization: Bearer YOUR_KEY. |
403 | The plan does not include this, or a required password is wrong. | Check the plan table, or the message. |
404 | The link or click does not exist, or belongs to someone else. Both look the same on purpose. | Check the id. |
422 | A conversion field is not valid, or the click is too old to count. | Fix the field named in message. |
429 | More requests in a minute than the plan allows. | Wait for the seconds in the Retry-After header. |
501 | The 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.
| Plan | Requests a minute | API access | Links a month | Raw clicks kept |
|---|---|---|---|---|
| Free | 60 | Read and change | 500 | 365 days |
| Pro | 120 | Read and change | 5,000 | 1,095 days |
| Team | 300 | Read and change | 25,000 | 3,650 days |
| Business | 600 | Read and change | 100,000 | No limit |
| Organization | 1,200 | Read and change | Agreed per customer | No 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 a429answer 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.
| Feature | Free | Pro | Team | Business | Organization |
|---|---|---|---|---|---|
| Password on a link | Yes | Yes | Yes | Yes | Yes |
| Expiry date | Yes | Yes | Yes | Yes | Yes |
| Click limit | Yes | Yes | Yes | Yes | Yes |
| Targeting by country, device and language | Yes | Yes | Yes | Yes | Yes |
| App deep links | Yes | Yes | Yes | Yes | Yes |
| Campaigns | No | Yes | Yes | Yes | Yes |
| Conversions | No | Yes | Yes | Yes | Yes |
| Webhooks | No | Yes | Yes | Yes | Yes |
| Raw click export | No | Yes | Yes | Yes | Yes |
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.