Getting Started

Understanding Rate Limits

Welcome to our guide on rate limits! To ensure our Payment Gateway (https://pay.izipay.ao/) stays fast, reliable, and fair for everyone, we place a few friendly speed limits on API requests.

Whenever you make requests, we count them in one-minute windows. If you happen to send too many requests in a single minute, our API will kindly ask you to slow down by returning an HTTP 429 Too Many Requests error.

Need a higher limit? The limits outlined below are standard starting points. If your business is growing and you're naturally hitting these limits during everyday operations, we want to help! Just contact IZI Support and we can discuss adjusting the quotas for your merchant account.

How Limits are Applied

Think of your limits as a personalized allowance. The allowance is tied to your Merchant / Tenant profile based on your authentication token. This means your limits are yours alone, and you don't share them with other businesses!

Speed Limits by Operation

Different types of API requests take different amounts of processing power. To keep things running smoothly, we categorize requests into three buckets:

1. Heavier Writes (State Changes)

Limit: ~100 requests per minute
What it covers: These are actions that create or permanently change data (mostly POST requests).
Examples: Creating a new payment, generating PPR references, issuing refunds, or canceling an authorization.
Endpoints: POST /api/payments, POST /api/payments/{id}/cancel, POST /api/references/ppr/bulk, etc.

2. Read & Sync (Getting Data)

Limit: ~500 requests per minute
What it covers: These are lighter actions where you are just asking us for information or syncing statuses (GET and some POST requests).
Examples: Checking the status of a payment, listing past refunds, or retrieving a PPR history.
Endpoints: GET /api/payments, GET /api/payments/{id}, POST /api/payments/{id}/sync.

3. Physical Terminals (POS)

Limit: ~1000 requests per minute
What it covers: In-store hardware terminals require very fast, high-volume polling. These have their own dedicated, high-speed lane!
Examples: Opening, closing, or checking the status of a physical terminal.

If an endpoint somehow fits into two categories, we always apply the stricter (lower) limit to ensure platform stability.

What to do if you get a 429 Error

Hitting a speed limit happens to the best of us! If you receive an HTTP 429 error, here are the best practices to handle it smoothly:

Take a breath (Slow down): Look for the Retry-After header in our response. It will tell you exactly how many seconds to wait before trying again.
Use Exponential Backoff: When retrying a failed request, wait a little longer after each attempt (e.g., 1s, 2s, 4s, 8s). This prevents your system from accidentally overwhelming ours.
Be careful with POST requests: If a GET request fails, retrying it is harmless. But if a POST request (like creating a payment) gets a 429, don't blindly retry it! You might accidentally charge a customer twice. Always use unique Order IDs or References so we know it's a retry and not a new transaction.
Optimize your code: If you are polling for a payment status every 100 milliseconds, consider slowing it down to every 2 seconds. Or, use batch endpoints if you need to create multiple PPRs at once!

Last modified on July 14, 2026

Error Handling Portal Guide

Speed Limits by Operation

Different types of API requests take different amounts of processing power. To keep things running smoothly, we categorize requests into three buckets:

1. Heavier Writes (State Changes)

Limit: ~100 requests per minute

What it covers: These are actions that create or permanently change data (mostly POST requests).

Examples: Creating a new payment, generating PPR references, issuing refunds, or canceling an authorization.

Endpoints: POST /api/payments, POST /api/payments/{id}/cancel, POST /api/references/ppr/bulk, etc.

2. Read & Sync (Getting Data)

Limit: ~500 requests per minute

What it covers: These are lighter actions where you are just asking us for information or syncing statuses (GET and some POST requests).

Examples: Checking the status of a payment, listing past refunds, or retrieving a PPR history.

Endpoints: GET /api/payments, GET /api/payments/{id}, POST /api/payments/{id}/sync.

3. Physical Terminals (POS)

Limit: ~1000 requests per minute

What it covers: In-store hardware terminals require very fast, high-volume polling. These have their own dedicated, high-speed lane!

Examples: Opening, closing, or checking the status of a physical terminal.

If an endpoint somehow fits into two categories, we always apply the stricter (lower) limit to ensure platform stability.

What to do if you get a 429 Error

Hitting a speed limit happens to the best of us! If you receive an HTTP 429 error, here are the best practices to handle it smoothly:

Take a breath (Slow down): Look for the Retry-After header in our response. It will tell you exactly how many seconds to wait before trying again.

Use Exponential Backoff: When retrying a failed request, wait a little longer after each attempt (e.g., 1s, 2s, 4s, 8s). This prevents your system from accidentally overwhelming ours.

Be careful with POST requests: If a GET request fails, retrying it is harmless. But if a POST request (like creating a payment) gets a 429, don't blindly retry it! You might accidentally charge a customer twice. Always use unique Order IDs or References so we know it's a retry and not a new transaction.

Optimize your code: If you are polling for a payment status every 100 milliseconds, consider slowing it down to every 2 seconds. Or, use batch endpoints if you need to create multiple PPRs at once!

Last modified on July 14, 2026