Rate limits
To keep the Report API fast and available for all customers, Tranzila limits the number of requests a single IP address can send.
| Limit | Maximum requests | Window |
|---|---|---|
| Per second | 30 | 1 second |
| Per minute | 1,000 | 60 seconds |
Both limits apply at the same time. Exceeding either one blocks the sending IP address.
Scope
- Per IP address. Requests are counted per public (source) IP address, regardless of API key, terminal, or endpoint. If several servers or applications share one outgoing IP address (for example, an office network or a cloud NAT gateway), their combined traffic counts toward the same limit.
- Every request counts, including requests rejected for an invalid signature or a validation error.
- Endpoints covered: all endpoints served from
https://report.tranzila.com, including/v1/transactionand/v1/terminals/settings/fields/list. Requests tohttps://api.tranzila.com, including transaction processing, are not subject to these limits.
Staying within the limits
Design your integration to stay comfortably below both limits, leaving a margin for network and timing differences.
- Route all requests from each outgoing IP address through a single throttled queue.
- Avoid parallel bursts, such as one simultaneous request per terminal.
- Prefer one request covering a longer date range over many small requests.
- Cache data that rarely changes, such as the response of
/v1/terminals/settings/fields/list. - Poll at reasonable intervals, never in tight loops.
- Retry failed requests with exponential backoff, never immediately.
Rate limit response
A request that exceeds a limit is rejected with HTTP status 429 Too Many Requests, a Retry-After header, and the following JSON body:
HTTP/1.1 429 Too Many Requests
Retry-After: 60
Content-Type: application/json
{
"error_code": 20006,
"message": "Too many requests. Your IP has been blocked for 1 minute.",
"limit_per_second": 30,
"limit_per_minute": 1000,
"retry_after_seconds": 60
}
| Field | Type | Required | Description |
|---|---|---|---|
error_code | integer | Yes | 20006 — the IP address is temporarily blocked due to rate limiting. |
message | string | Yes | Human-readable description. Do not parse this field; use retry_after_seconds instead. |
limit_per_second | integer | Yes | Per-second limit currently in force. |
limit_per_minute | integer | Yes | Per-minute limit currently in force. |
retry_after_seconds | integer | Yes | Block duration in seconds. Same value as the Retry-After header. |
Note: While the block is active, some requests may be rejected with a non-JSON error page instead of the response above. Treat any such response as a
429.
Recovering from a block
The block lasts 60 seconds from the request that exceeded the limit. Requests sent during the block do not extend it, but all of them are rejected. Allow up to 3 minutes from the first rejected request for access to be fully restored.
- Stop sending requests from the affected IP address, including from any other application that shares it.
- Wait for the
Retry-Aftervalue plus an additional 60 seconds. - Resume at a reduced rate through your throttled queue.
- If requests are still rejected, keep waiting with increasing delays rather than retrying in a loop.
response = send(request)
if response.status == 429 or response is not valid JSON:
wait = response.header("Retry-After") or 60
pause all requests from this IP for (wait + 60) seconds
resume through the throttled queue, with exponential backoff
Higher limits or unexpected blocks
If your integration needs higher capacity, or you believe your IP address was blocked in error, contact Tranzila technical support at support@interspace.net and include:
- The public IP address or addresses your requests are sent from.
- The date and time of the block, including the time zone.
- The endpoints you call and your expected number of requests per minute.
Note: Tranzila may adjust these limits to protect service availability. The limits currently in force are always returned in the
429response body.