API requests can fail for various reasons—network issues, rate limits, timeouts, or temporary service disruptions. Here’s how to handle them effectively.

Retries

---

To enhance reliability, implement a retry strategy based on these best practices:

• Retry Only When Necessary
  Limit retries to specific HTTP status codes:
  • 5xx (Server Errors)
  • 429 (Rate Limits)
  • 408 (Timeouts)
• Use Exponential Backoff with Jitter
  Prevent server overload by gradually increasing the wait time between retries, adding randomness (jitter) to avoid traffic spikes.
• Leverage Idempotency Keys
  If supported, use idempotency keys to prevent duplicate processing of the same request.

Timeouts

---

Our APIs are designed for fast failure detection and retry support. Setting appropriate client-side timeouts ensures consistent request handling.

• SaaS Timeout Limit
  In SaaS environments, API requests timeout after 29 seconds.

📘

Note

If you’re using Midaz open-source, you can adjust timeout settings in the Helm file.

Rate Limits

---

To maintain system stability, our API enforces a rate limit of 1,000 requests per minute per IP address. This limit is applied separately to each environment—sandbox and live. If exceeded, the API responds with an HTTP 429 status code and a relevant error message.

📘

Note

Midaz open-source users can configure rate limits directly in the Helm file.