Skip to main content

Throttling & quotas

Throttling (also called rate limiting) is a mechanism that limits how many requests you can make to the API within a given time window. It exists to protect the service — without it, a single client sending thousands of requests per second could slow down or disrupt the API for everyone else. Throttling ensures fair access and keeps the system stable for all users.

The Medipim API allows 100 requests per minute. If you exceed this rate, the API returns HTTP status code 429 with error code too_many_requests (see Error handling). This is not an error in your code — it simply means you need to wait before sending the next request.

tip

The PHP client automatically throttles your requests to respect this rate.

How the throttling works​

  1. A client sends a request to the API.
  2. The API checks whether the current request exceeds the allowed number of calls.
  3. If the request is within limits, the API performs the operation as usual.
  4. If the request exceeds the limit, the API returns a 429 error response.
  5. The client must wait before making further API calls.

Strategies for staying within limits​

If you expect to make more than 100 calls per minute, consider these approaches:

  • Store data locally and synchronize regularly. This avoids hitting the rate limit during normal operations.
  • Space your requests over time. Distribute calls evenly across the minute window.
  • Use multiple API keys so you can switch to a different key when the limit has been reached.

How do I sync the full product range for the first time?​

When you first integrate with Medipim, you'll typically want to pull in the entire product catalog. With a rate limit of 100 requests per minute and potentially tens of thousands of products, fetching them page by page through the regular query endpoint would take a very long time.

This is where the stream endpoint comes in. A single request returns all matching products as a continuous stream in JSON Lines format — each line in the response is a JSON object for one product. Because it's a single request, you don't run into the rate limit, and you can start processing products as they arrive rather than waiting for the entire response to finish.

Use the query endpoint when you need pagination for smaller data sets or during development and testing.

tip

When using the stream endpoint, log which products have been processed so you don't need to start over if the connection is interrupted.