From 2f72f5abb47c451aaf390ae3b09ea6592a831668 Mon Sep 17 00:00:00 2001 From: Remco Suiker <114516646+Remco-Suiker@users.noreply.github.com> Date: Tue, 13 Jun 2023 13:23:22 +0200 Subject: [PATCH] docs: Add rate limiting for shipments, drop_off_points and fulfilment (#65) * docs: Add rate limiting for shipments, drop_off_points and fulfilment * docs: Add rate limiting for shipments, and return_shipments. Sort list. * docs: Set apply date at Sept 1st * docs: updated date * docs: add default route to rate limiting list --------- Co-authored-by: Wouter in 't Veld --- src/api-reference/01.requests.md | 60 +++++++++++++++++++++----------- 1 file changed, 40 insertions(+), 20 deletions(-) diff --git a/src/api-reference/01.requests.md b/src/api-reference/01.requests.md index 8f2a43c9..56078c60 100644 --- a/src/api-reference/01.requests.md +++ b/src/api-reference/01.requests.md @@ -70,23 +70,43 @@ A PATCH request performs a partial update to an existing resource. The client specifies the URI for the resource. The request body specifies a set of changes to apply to the resource. This can be more efficient than using -## 1.D Rate limiting(WIP) - -Rate limits may apply to many of our endpoints. You cannot receive data after -you have exceeded the limit. The rate limiting will be reached when you make -more than xxx requests per minute. The limit automatically resets after x -minute(s). - -Example: If you make 100 requests within 15 seconds to the same endpoint with an -applied rate limit of 100 request per 5 minutes, you will be able to continue 5 -minutes later. Hence the applied timeframe of the rate limit (5 minutes) will -also be applied for the cooldown period. - -| Method | Endpoint | Rate limit | -| ------ | ------------------------ | ---------------------- | -| POST | `/webhook_subscriptions` | 30 calls in 5 minutes | -| GET | `/webhook_subscriptions` | 150 calls in 5 minutes | -| DELETE | `/webhook_subscriptions` | 30 calls in 5 minutes | -| GET | `/tracktraces/{ids?}` | 100 calls in 5 minutes | -| GET | `/pickup_locations` | 30 calls in 5 minutes | -| GET | `/delivery_options` | 30 calls in 5 minutes | +## 1.D Rate limiting + +Default rate limits apply to many of our documented endpoints. +Customers who would like a higher rate limit can contact us to discuss the possibilities +(e.g. increasing the limit, or using a webhook). +When the limit is reached for a Method/Endpoint combination, any additional call will return +an HTTP 429 (Too Many Requests), effectively ignoring the request. +A sliding window is used to determine the rate limit. +Calls resulting in an HTTP 429 also count as requests, so it is better to wait a while before retrying than continually +retrying and getting additional HTTP 429 responses. +Waiting 5 minutes will definitely reset the rate limit for the used Method/Endpoint combination. + +Example: If you make 100 GET requests within 15 seconds to the same endpoint with an +allowed rate limit of 100 request per 5 minutes, you will only be able to continue sending GETs 4 minutes 45 +seconds later. Sending some POSTs to the same endpoint is allowed though, it follows its own rate limit. + +| Method | Endpoint | Rate limit | +|--------|-------------------------------------------------|---------------------------| +| GET | `/` | 30 calls in 5 minutes * | +| GET | `/drop_off_points` | 300 calls in 5 minutes * | +| GET | `/fulfilment/orders` | 100 calls in 5 minutes * | +| POST | `/fulfilment/orders` | 100 calls in 5 minutes * | +| PUT | `/fulfilment/orders` | 100 calls in 5 minutes * | +| GET | `/fulfilment/orders/{identifier}` | 100 calls in 5 minutes * | +| DELETE | `/fulfilment/orders/{identifier}` | 100 calls in 5 minutes * | +| GET | `/fulfilment/orders/{identifiers}/packing_slip` | 100 calls in 5 minutes * | +| GET | `/pickup_locations` | 30 calls in 5 minutes | +| POST | `/return_shipments` | 30 calls in 5 minutes * | +| GET | `/shipments` | 300 calls in 5 minutes * | +| PATCH | `/shipments` | 300 calls in 5 minutes * | +| POST | `/shipments` | 300 calls in 5 minutes * | +| PUT | `/shipments` | 300 calls in 5 minutes * | +| GET | `/shipments/{ids}` | 1000 calls in 5 minutes * | +| DELETE | `/shipments/{ids}` | 300 calls in 5 minutes * | +| GET | `/shipment_labels/{ids}` | 300 calls in 5 minutes * | +| GET | `/tracktraces/{ids?}` | 100 calls in 5 minutes | +| GET | `/webhook_subscriptions` | 150 calls in 5 minutes | +| POST | `/webhook_subscriptions` | 30 calls in 5 minutes | +| DELETE | `/webhook_subscriptions` | 30 calls in 5 minutes | +Note: Rate limits for endpoints marked with * will be applied on August 1st, 2023.