Rate Limits

The Convirza V3 API applies rate limits so the platform stays responsive for everyone. Limits are applied per billing account, and requests from a single source IP address are also limited. Both use a fixed one minute window.

Find your limit

Your limit is returned on every response. You do not need to guess it or hardcode it.

Header	Meaning
`X-RateLimit-Limit`	Requests allowed in the current window
`X-RateLimit-Remaining`	Requests still available in this window
`X-RateLimit-Reset`	Unix timestamp, in seconds, when the window resets

Make any authenticated request and read X-RateLimit-Limit. Watching X-RateLimit-Remaining and easing off before it reaches zero is more reliable than reacting to errors after the fact.

The account limit is shared

The account limit applies across your whole billing account. Every user, every API key and every integration under that account draws from the same allowance.

Running more workers in parallel does not increase your throughput. It consumes the same window faster.

When you exceed a limit

You receive HTTP 429 with this response body:

{
  "code": 429,
  "message": "API rate limit exceeded for your account",
  "limit": 0,
  "remaining": 0,
  "resetAt": 0
}

Field	Meaning
`code`	Always `429`
`message`	Human readable cause
`limit`	Your allowance for the current window
`remaining`	Always `0` on a 429
`resetAt`	Unix timestamp, in seconds, when you can resume

Handling 429 correctly

Treat 429 as retryable. Your request was not malformed, only badly timed.

Wait until resetAt before retrying. Retrying into a closed window makes the problem worse.

Add jitter if you run more than one worker, so they do not all resume at the same instant.

Back off exponentially if you receive several 429s in a row.

Share a limiter across your workers. The account allowance is shared, so uncoordinated parallelism only wastes it.

Staying under the limit

Batch where an endpoint supports it. One request returning 200 records costs one request, not 200.

Use the largest page size an endpoint allows rather than making many small calls.

Cache data that rarely changes, such as groups, users, tags, industries and ad sources.

Use webhooks instead of polling. If you are calling an endpoint on a timer to detect new activity, subscribe to the event instead. This is usually the single largest reduction in request volume.

Filter server side using query parameters, rather than fetching broadly and filtering in your own code.

Need a higher limit?

Contact support@convirza.com with your account ID, the endpoints you are calling, and your expected peak request rate.

Rate Limits

Find your limit#

The account limit is shared#

When you exceed a limit#

Handling 429 correctly#