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 <[email protected]>

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.