How to Handle API Rate Limits and Avoid 429 Errors

TABLE OF CONTENTS

• Understanding Rate Limits

• How to Handle 429 Responses

• Troubleshooting

  • Step 1: Analyze the "RateLimit-Type" Header

  • Step 2: Implement a Prevention Strategy

  • Step 3: Emergency Handling (The "Retry" Mechanism)

• API Integration Best Practices

  • 1. Use Serial Execution Instead of Parallel Requests

  • 2. Implement Smart Caching with Webhooks

  • 3. Optimize Data Fetching

  • 4. Filter the Data

  • 5. Check the "Retry-After" Header

  • 6. Keep an Error Log

Understanding Rate Limits

When integrating with the Precoro API, it's essential to manage your request flow efficiently. Precoro uses rate limits to ensure system stability and fair usage for all clients. If your integration exceeds these limits, including duplicate-request limits, the API will return a 429 Too Many Requests error, and your requests won’t be completed.

You may find the full list of established limits here.

Key Limits to Remember:

• Concurrency Limit: Maximum 1 request per second.
  • Impact: Sending multiple requests simultaneously (e.g., using parallel threads or consequent requests without a timeout) will result in getting a 429 Too Many Requests error.
• Duplicate Request Limit (For GET requests): An identical request can’t be sent within 1 minute after the original.
  • Impact: Repeatedly requesting the exact same endpoint with the same parameters (e.g., polling for invoice status every 5 seconds) will trigger an error.
  • Note: This limit applies only to data retrieval (GET requests). It does not apply to data creation or updates (POST, PUT, PATCH methods).
• Hourly/Daily Volume: There are also limits for total requests per hour (1500) and per day (3000).

How to Handle 429 Responses

If you receive a 429 Too Many Requests status code, your integration must pause and wait before retrying. Requests resent immediately won’t be completed.

Example 429 Response:

Check the response for details on when you can resume:

1. RateLimit-Type: Indicates which specific limit was exceeded (e.g., Seconds limiter, Route based limiter).
2. RateLimit-Retry-After: Shows the date and time (in UTC) when the block will be lifted.
   • Example: 2025-12-12 15:30:01 UTC
3. RateLimit-Limit: Informs you how many requests are allowed within the specified limit.

Troubleshooting

Please follow the steps explained below to optimize your integration logic based on the error details. The goal is to prevent the error in the first place, ensuring faster and more reliable performance.

Step 1: Analyze the "RateLimit-Type" Header

The RateLimit-Type header in the response helps you clearly understand why your request was blocked. Please use it to identify the flaw in your code.

Step 2: Implement a Prevention Strategy

To ensure your integration is stable and works without delays, it should be designed to stay within limits.

• For Loops: If you‘re iterating through a list of IDs to fetch details, ensure there is at least a 1-second delay between iterations. There can’t be more than 1 subsequent request per second.
• For Webhooks: If you receive a webhook and need to fetch data, don’t trigger the fetch immediately if you expect high-volume webhooks. Queue the jobs and process them sequentially with 1-second intervals.

Step 3: Emergency Handling (The "Retry" Mechanism)

We recommend using retries as a fallback mechanism rather than your primary flow control.

1. If you receive a 429 error despite your optimizations, check the RateLimit-Retry-After header.
2. Log the error so you can investigate why the optimization failed.
3. After that, pause the execution until the specified time and retry the request once.

API Integration Best Practices

To avoid hitting limits, please follow these guidelines when designing your integration:

1. Use Serial Execution Instead of Parallel Requests

Keep in mind that the API allows only 1 request per second.

• Don't: Send asynchronous or multi-threaded requests (e.g., sending 10 GET requests at the exact same second).
• Do: Process requests sequentially (one by one) with a small delay (e.g., 1.1 seconds) between them.

2. Implement Smart Caching with Webhooks

• Don't: Repeatedly request the same endpoints to check for status updates.
• Do: Fetch the data once and store it locally. To keep it up to date, subscribe to Webhooks. Precoro will notify your system immediately when an event occurs (e.g., the supplier is changed). Use this signal to invalidate your local cache and fetch fresh data only when necessary. Learn more about setting up webhooks in this guide.

3. Optimize Data Fetching

These rules apply when you process linked documents (e.g., invoices related to purchase orders).

• Don't: Fetch a list of IDs and then immediately iterate through them requesting details for each ID without pauses. This will trigger the per-second limit.
• Do: Add a deliberate delay between detail requests in your loop.

4. Filter the Data

Whenever you retrieve data, ensure you’re only requesting what you need.

• Don’t: Request all the available data to filter it locally.
• Do: Use filters and review parameters to ensure only essential ones are included. The "modifiedSince" filter will help you retrieve the most up-to-date data and reduce redundant requests.
  For example, to get all POs created or updated since October 10, 2025, use:
  https://api.precoro.com/purchaseorders?modifiedSince=2025-10-10T00:00:00

5. Check the "Retry-After" Header

Automated scripts often try to restart immediately after a failure.

• Don't: Retry the same request immediately if it's failed in your scripts. This will only extend the blocking period.
• Do: Implement an error handler to respect the time provided in the RateLimit-Retry-After header.

6. Keep an Error Log

• Don’t: Let the errors go unnoticed until critical issues arise.
• Do: Log errors with sufficient detail to allow easier and more effective troubleshooting. Logging is especially relevant for response codes 4xx and 5xx.