Several changes on quotas and limitations details

* Move REST API Limitations and fair usage details to a dedicated page named "Limitations" (as it is done for Event Platform and GraphQL)
* Add a link to this page in GraphQL limitations page
* Change the quota wording in Event Platform to remove the 5M "fake" limit.

Author: ThomasBigot

content/event-platform/limitations.md

@@ -8,9 +8,9 @@
 
 **Event Platform Quotas:**
 
-Our Event platform has specific quotas designed to ensure optimal performance and fair usage for all users.
-- **Weekly Event Limit**: You can distribute up to 5 million events per week for the light payload.
-- **Exceeding Limits**: If you exceed this limit occasionally, your usage will not be interrupted. However, habitual overages may require further discussion to optimize your usage.
+Our event platform does not impose specific quotas.
+
+However, to ensure optimal performance and fair use for all users, heavy usage (millions of events per day) may require further discussion to help you optimise your usage.
 
 ::: panel-link Consult now our FAQ [Next](/event-platform/faq.html)
 :::

content/graphql/limitations.md

@@ -13,14 +13,17 @@ By setting boundaries, we avoid complex or large queries that could potentially
 :::warning
 Understanding **that the limitations are not static and will adapt over time based on usage and requirements is vital**.
 
-With the **GraphQL API** being a recent addition to Akeneo, our priority is to ensure the stability of the PIM by carefully assessing all risks.
+The **GraphQL API** being based on Akeneo's PIM REST API, our priority is to ensure the stability of the PIM by carefully assessing all risks.
 
 If you encounter any **challenges** with the `rate limits`, please don't hesitate to reach out by opening a support ticket.
 
 Your insights are invaluable in fine-tuning our system for optimal performance.
+
+You can also find more details about the [REST API Limitations](/documentation/limitations.html)
 :::
 The **GraphQL API** is limited to `500req/10s` per **PIM URL.**
 
+
 ## Query complexity limitations
 
 Each query will have a cost complexity depending on the requested data.
@@ -127,11 +130,13 @@ This is an important tip to keep in mind.
 :::warning
 Understanding **that the limitations are not static and will adapt over time based on usage and requirements is vital**.
 
-With the **GraphQL API** being a recent addition to Akeneo, our priority is to ensure the stability of the PIM by carefully assessing all risks.
+The **GraphQL API** being based on Akeneo's PIM REST API, our priority is to ensure the stability of the PIM by carefully assessing all risks.
 
 If you encounter any **challenges** with the `depth limit`, please don't hesitate to reach out by opening a support ticket.
 
 Your insights are invaluable in fine-tuning our system for optimal performance.
+
+You can also find more details about the [REST API Limitations](/documentation/limitations.html)
 :::
 
 

content/rest-api/limitations.md

@@ -0,0 +1,44 @@
+# Limitations
+
+Our API facilitates the integration of Akeneo PIM with external systems.
+To maintain optimal user experience and platform stability, our platform employs various protection mechanisms to prevent over-usage.
+
+To guarantee fair usage, please adhere to the following usage guidelines:
+
+## Maximum Concurrent API Calls
+
+- Per PIM Connection: Up to 4 concurrent API calls are allowed for each individual PIM connection.
+- Per PIM Instance: Up to 10 concurrent API calls are allowed across the entire PIM instance.
+
+
+## Rate Limits Within a Specific Amount of Time
+
+- General API Requests: up to 100 API requests per second per PIM instance.
+- [updating & creating attribute options](https://api.akeneo.com/api-reference.html#patch_attributes__attribute_code__options):  up to 3 API requests per second per PIM instance.
+
+
+## Handling Over-Usage
+
+If your API usage exceeds these limits, the platform’s protection mechanisms may be triggered, resulting in blocked requests and  HTTP status code 429 responses.
+As a REST API consumer, you have to keep in mind that your integration with Akeneo PIM should anticipate this throttling and should be able to handle failures.
+
+Bursts are allowed, but continuous over-usage will trigger the protection sooner.
+
+To effectively manage and mitigate over-usage, we recommend implementing the following strategies:
+
+**Check for "Retry-After"**
+
+   If the HTTP 429 response includes a "Retry-After" header, wait the specified number of seconds before retrying.
+
+**Implement Exponential Backoff**
+
+   Use increasing delays between retry attempts (e.g., 10s, 30s, 60s) to reduce the load on the API.
+
+**Use Batch Endpoints**
+
+   Combine multiple requests into a single API call using batch endpoints to minimize the number of calls.
+
+**Implement a Cache Layer**
+
+   Cache frequently accessed data on the client side to reduce repetitive API requests and improve response times.
+   

tasks/build-doc.js

@@ -604,6 +604,7 @@ gulp.task('build-rest-api', ['clean-dist','less'], function () {
         'pagination.md': 'Pagination',
         'update.md': 'Update behavior',
         'filter.md': 'Filters',
+        'limitations.md': 'Limitations',
         'troubleshooting.md': 'Troubleshooting guide'
     };