API incwo : des limites d’usage désormais progressives — comment bien les gérer

Pour garantir à tous nos clients une plateforme rapide et stable, l’API incwo applique des limites d’appels (rate limits) par seconde, par minute et par heure. Ces limites n’ont pas changé. Ce qui change, c’est ce qui se passe quand vous les dépassez de façon répétée.

Ce qui change

Jusqu’ici, un appel au-delà de la limite recevait simplement une erreur 429, et l’appel suivant pouvait repasser dès la fenêtre de temps suivante. Résultat : certaines intégrations « mal réglées » réessayaient en boucle, sans jamais lever le pied — au détriment de leurs propres performances comme de la plateforme.

Désormais, les dépassements répétés sont sanctionnés de façon progressive :

• au premier dépassement, vous êtes bloqué quelques instants ;
• si vous recommencez juste après, la durée de blocage augmente à chaque récidive (de 1 minute jusqu’à plusieurs heures) ;
• réessayer pendant un blocage n’aboutit jamais : cela ne fait que maintenir — voire prolonger — la sanction ;
• dès que votre intégration se calme, la pénalité retombe automatiquement après une période sans dépassement.

En clair : une intégration bien élevée ne verra jamais la différence. Une intégration qui s’acharne, elle, sera de plus en plus freinée.

La réponse 429, en détail

Quand une limite est atteinte, l’API renvoie un statut HTTP 429 avec :

• un en-tête HTTP standard Retry-After (en secondes) ;
• un corps JSON contenant le même délai dans le champ retry_after.

HTTP/1.1 429 Too Many Requests
Retry-After: 300
Content-Type: application/json

{ “errors”: [ { “code”: 429, “message”: “Rate limit exceeded”, “retry_after”: 300, “details”: [ “Per minute limit reached (61/60)” ], “info”: “Check https://www.incwo.com/site/developer#rate-limit” } ] }

Ici, Retry-After: 300 signifie : attendez 300 secondes avant de réessayer.

La bonne pratique : respecter Retry-After + backoff exponentiel

La règle d’or : ne jamais réessayer immédiatement sur un 429. Lisez l’en-tête Retry-After, attendez le délai indiqué, et appliquez un backoff exponentiel en cas de 429 successifs.

Exemple en Python :

```python
import time
import requests

def call_incwo(url, **kwargs):
    backoff = 1

    for attempt in range(6):
        resp = requests.get(url, **kwargs)

        if resp.status_code != 429:
            return resp

        # Respecte le délai indiqué par le serveur,
        # sinon utilise un backoff exponentiel.
        wait = int(resp.headers.get("Retry-After", backoff))
        time.sleep(wait)

        backoff = min(backoff * 2, 600)

    raise RuntimeError(
        "incwo API : la limite de débit n'a pas été levée après plusieurs tentatives."
    )
```

Quelques conseils pour ne jamais y être confronté

• Lissez vos traitements de masse : insérez une petite pause entre les appels plutôt que d’envoyer des rafales.
• Mettez en cache les données qui changent peu, au lieu de les redemander en boucle.
• Préférez les webhooks aux pollings fréquents pour être notifié des changements.
• Traitez le 429 comme un signal, pas comme un obstacle à contourner par des retries agressifs.

En résumé

Rien à faire si votre intégration respecte déjà les limites. Si ce n’est pas le cas, un seul réflexe suffit : respecter Retry-After. C’est meilleur pour vos performances… et pour tout le monde.

Détails techniques : Documentation développeur — Rate limits