🚦 API Limits

To ensure fair usage and maintain the stability of the FlamPix Gateway API, rate limiting is applied to all endpoints. These limits are enforced based on the IP address and, for authenticated routes, the Client ID.

📊 Gateway Limits (Public API)

Environment	Rate Limit (Sustained)	Window	Description
Production	120 requests/min	60s	Standard limit for production traffic.
Sandbox	30 requests/min	60s	Lower limit for development and testing.

Note: Authenticated clients also have a specific rate_limit_per_minute configured in their account, which may be lower or higher than the global edge limit depending on the plan.

🛡️ Other API Limits

Endpoint	Rate Limit	Burst Handling	Notes
General API	1000 req/15min	-	General limit for non-critical internal APIs.
Account Info	120 req/min	Flexible	For checking account existence or creating charges.

🚦 Understanding Rate Limiting

Rate limiting controls how many requests a user can make within a specific time frame. When you exceed these limits, the API returns a 429 Too Many Requests status code.

Key Concepts

Rate Limit: The maximum number of requests allowed within a specific time window (e.g., 1 minute).

Window: The duration of time in which the requests are counted.

Reset: When the window expires, your request count is reset to zero.

Example Scenario (Sandbox)

If you are using the Sandbox environment with a limit of 30 requests per minute:

You can send up to 30 requests between 10:00:00 and 10:01:00.

If you send a 31st request at 10:00:45, it will be rejected with a 429 error.

You must wait until 10:01:00 for the counter to reset before sending more requests.

🔄 Handling Rate Limits

If you receive a 429 Too Many Requests response, your application should stop sending requests for a short period.

Response Headers

The API includes headers in every response to help you monitor your usage:

X-RateLimit-Limit: The maximum number of requests allowed in the current window.

X-RateLimit-Remaining: The number of requests you have left in the current window.

X-RateLimit-Reset: The time (in seconds) until the current window resets.

Retry-After: The number of seconds to wait before making a new request (only present on 429 responses).

Best Practices

Implement Backoff: If you hit a limit, use an exponential backoff strategy (wait 1s, then 2s, then 4s...) before retrying.

Spread Requests: Avoid sending bursts of requests at the exact same second. Distribute them evenly over the minute.

Cache Data: Cache responses locally whenever possible (e.g., user info, exchange rates) to reduce the number of calls.

Use Webhooks: Instead of polling GET /deposits/:id repeatedly, rely on Webhooks to get real-time updates.

📊 Gateway Limits (Public API)#

🛡️ Other API Limits#

🚦 Understanding Rate Limiting#

Key Concepts#

Example Scenario (Sandbox)#

🔄 Handling Rate Limits#

Response Headers#

Best Practices#