Corriger les erreurs de limite de débit (429) de HiAPI : causes et solutions

Lorsque la passerelle HiAPI renvoie HTTP 429 Too Many Requests, cela signifie que votre clé API a dépassé, sur une courte période, la fréquence de requêtes ou la limite de concurrence autorisée sur https://api.hiapi.ai/v1/tasks (ou sur le point de terminaison d'interrogation GET /v1/tasks/{taskId}). Le corps de la réponse suit l'enveloppe d'erreur unifiée de HiAPI — {"error":{"type":"hiapi_error","code":"...","request_id":"..."}} — accompagnée d'un code de statut 429. Le résoudre ne nécessite presque jamais d'envoyer un e-mail au support ; il suffit d'ajouter une petite logique de « nouvelle tentative + limitation de débit » côté client. Cet article explique ce qu'est cette erreur, pourquoi elle se déclenche et les étapes concrètes pour la faire disparaître.

À quoi ressemble un 429 de HiAPI

Une requête typique au niveau réseau ressemble à peu près à ceci :

> POST /v1/tasks HTTP/1.1
> Host: api.hiapi.ai
> Authorization: Bearer hi-sk-...
> Content-Type: application/json

< HTTP/1.1 429 Too Many Requests
< Content-Type: application/json
<
{"error":{"type":"hiapi_error","code":"rate_limit_exceeded","request_id":"req_..."}}

Deux points essentiels :

• Le code de statut est 429, pas 401/403. 401 indique que la clé est incorrecte ou manquante ; 429 indique que la clé est valide, mais que vous envoyez trop vite. Ne confondez pas les deux.
• Le corps de la réponse est un JSON dans l'enveloppe hiapi_error. Certains clients HTTP n'exposent par défaut que le code de statut ; si votre code réessaie silencieusement sans journaliser, vous perdrez des indices de diagnostic comme request_id.

Si vous appelez les modèles GPT Image 2, Nano-Banana, flux, Seedance, Wan ou HappyHorse, ils s'exécutent tous sur le même point de terminaison de tâches asynchrones et partagent donc la même facturation de débit par clé.

Causes courantes (par ordre de probabilité)

D'après notre expérience, de la plus à la moins probable :

1. Fan-out en rafale sur une seule clé (burst fan-out). Vous parcourez un lot de prompts et appelez POST /v1/tasks en parallèle pour chacun, sans limite de concurrence. Même une dizaine de créations de tâches simultanées suffisent à atteindre le plafond sur un nouveau compte.
2. Interrogation agressive de GET /v1/tasks/{taskId}. Une boucle serrée while True: poll(); sleep(0.2) compte comme autant de requêtes que la création de tâches. L'interrogation à intervalle inférieur à la seconde est la première cause du « je n'ai créé qu'une seule tâche et j'ai quand même un 429 ».
3. Limite de concurrence au niveau du compte. Les modèles plus lourds — vidéo (seedance-2.0, wan2.7-video/*, happyhorse-1.0) et variantes d'image @pro — sont soumis à des plafonds de tâches concurrentes plus stricts. Soumettre d'un coup un grand nombre de ces tâches provoque un 429 même si votre fréquence par minute est faible.
4. Une même clé partagée entre plusieurs environnements. dev, staging et prod utilisent tous la même HIAPI_API_KEY, et les volumes s'additionnent. Chaque environnement pris isolément est sous les limites, mais ensemble ils poussent la clé au-delà du plafond.
5. Quota du forfait épuisé. Un quota gratuit ou un forfait payant presque épuisé se manifeste parfois par un 429 plutôt qu'une erreur de facturation, surtout pendant les promotions.

Concernant les seuils précis : le nombre de requêtes par minute et les limites de concurrence de HiAPI dépendent du niveau de votre compte ; la plateforme ne publie pas de chiffre fixe. Les valeurs de concurrence ci-dessous (5, 3, 2) sont donc des points de départ empiriques, et non des limites officielles — ajustez-les en fonction de l'usage réel affiché dans le tableau de bord.

Étapes de correction

Procédez dans l'ordre. La plupart des équipes cessent de recevoir des alertes dès la 3e étape.

1. Ajouter un backoff exponentiel avec jitter

Tout client communiquant avec api.hiapi.ai doit, en cas de 429, réessayer avec un délai croissant — jamais immédiatement. Une implémentation sûre par défaut :

import random, time, requests

def post_task_with_backoff(body, key, *, max_retries=5):
    delay = 1.0
    for attempt in range(max_retries):
        r = requests.post(
            "https://api.hiapi.ai/v1/tasks",
            headers={"Authorization": f"Bearer {key}", "Content-Type": "application/json"},
            json=body, timeout=30,
        )
        if r.status_code != 429:
            r.raise_for_status()
            return r.json()
        retry_after = r.headers.get("Retry-After")
        wait = float(retry_after) if retry_after else delay + random.random()
        time.sleep(min(wait, 30.0))
        delay = min(delay * 2, 30.0)
    raise RuntimeError("rate-limited after retries")

Ce code fait deux choses correctement : plafonner le délai à 30 secondes ; et privilégier l'en-tête de réponse Retry-After lorsqu'il est présent. Même si votre réponse 429 ne contient pas de Retry-After, la stratégie « plafond + jitter » suffit à absorber la plupart des rafales.

2. Limiter la concurrence côté client par clé

Ajouter un sémaphore côté client est la modification la plus efficace à elle seule. Si vous ne savez pas quelle valeur choisir, commencez par 5 :

import asyncio, httpx

sem = asyncio.Semaphore(5)

async def create_task(client, body):
    async with sem:
        r = await client.post("https://api.hiapi.ai/v1/tasks", json=body, timeout=30)
        return r.json()

Cinq tâches simultanées sont confortables pour la plupart des comptes. Si vous avez encore des 429, descendez à 3. Les modèles vidéo lourds nécessitent généralement un sémaphore distinct et plus bas (essayez 2).

3. Passer de l'interrogation à callback.url

Pour les charges de production, interroger GET /v1/tasks/{taskId} n'est pas un bon défaut. Transmettez callback.url dans le corps de la requête et HiAPI vous enverra le résultat par POST lorsque la tâche atteindra son état terminal :

{
  "model": "Nano-Banana",
  "input": { "prompt": "a calm lake at dawn", "aspect_ratio": "16:9" },
  "callback": { "url": "https://your-domain.com/hiapi/callback", "when": "final" }
}

Cela réduit le schéma de requêtes de O(nombre de tâches × nombre d'interrogations) à O(nombre de tâches) — généralement une baisse du volume d'appels de 10 à 50 fois, et un remède quasi immédiat aux 429 liés à l'interrogation. Réservez GET /v1/tasks/{taskId} au débogage local et aux appels ponctuels à faible fréquence.

4. Ralentir le rythme d'interrogation et ajouter du jitter

Si vous ne pouvez pas utiliser de callback (script hors ligne, notebook local, réconciliation de secours), n'interrogez pas plus vite que toutes les 2 à 5 secondes, et ajoutez du jitter pour éviter que plusieurs workers avancent à l'unisson :

import random, time
time.sleep(2 + random.random() * 3)  # 2–5 secondes, avec jitter

5. Séparer les clés par environnement

Générez une clé pour chaque environnement sur la page des clés API HiAPI — dev, staging, prod. Les rafales de chaque environnement sont isolées les unes des autres, et si une clé fuite, elle peut être révoquée séparément sans affecter les autres environnements.

6. Vérifier l'usage actuel

Ouvrez le tableau de bord HiAPI pour confirmer si vous avez atteint une limite de concurrence ou de forfait, ou s'il s'agissait simplement d'une brève rafale ; les quotas de chaque forfait sont comparables sur la page de tarifs. Si votre usage est bien inférieur au forfait et que vous avez quand même des 429, la cause est presque certainement une rafale côté client, et non le compte lui-même.

Vérification minimale

Une fois la couche de nouvelles tentatives en place, une tâche Nano-Banana est le moyen le moins coûteux de vérifier que la chaîne fonctionne. Remplacez $HIAPI_API_KEY par votre clé :

curl -s -X POST https://api.hiapi.ai/v1/tasks \
  -H "Authorization: Bearer $HIAPI_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "Nano-Banana",
    "input": { "prompt": "a single red apple on a white table", "aspect_ratio": "1:1" }
  }'

Un succès ressemble à peu près à ceci : {"code":200,"data":{"taskId":"tk-hiapi-..."}}. Interrogez ensuite une fois :

curl -s -H "Authorization: Bearer $HIAPI_API_KEY" \
  https://api.hiapi.ai/v1/tasks/tk-hiapi-...

Le statut passe par queued → handling → archiving → success, et le data.output[0].url final est votre image. Si cet aller-retour renvoie 200 mais que vos tâches par lots renvoient encore des 429, le problème vient de la concurrence côté client, pas de votre clé.

Questions fréquentes

Pourquoi ai-je un 429 alors que je n'ai envoyé qu'une seule requête ?

Presque toujours parce que le volume réel de requêtes provient de la boucle d'interrogation, et non de la création de tâches. Interroger 5 tâches concurrentes à 200 ms d'intervalle représente à lui seul 25 requêtes par seconde. Ralentissez l'interrogation à 2–5 secondes, ou passez à callback.url.

HiAPI inclut-il toujours un en-tête Retry-After ?

Traitez Retry-After comme une valeur indicative : utilisez-le s'il est présent, sinon revenez au backoff exponentiel (1s, 2s, 4s… plafonné à 30s). Dans tous les cas, ne réessayez pas sans délai — cela ne ferait qu'amplifier la rafale.

429 et 401 / 403, est-ce la même chose ?

Non. 401 / 403 indiquent un échec d'authentification, avec la même enveloppe hiapi_error, par exemple {"error":{"code":"permission_denied","type":"hiapi_error","request_id":"req_..."}} (en pratique, le message d'un 401 indique « This API key is invalid. Check that it is correct... »). Si vous voyez 401/403, vérifiez la valeur de la clé sur la page des clés API — le backoff n'y changera rien.

Puis-je simplement augmenter la limite de débit ?

Si votre trafic nécessite réellement une limite de concurrence plus élevée, vérifiez d'abord les quotas de votre forfait sur la page de tarifs, puis contactez le support depuis là. En pratique, les correctifs ci-dessus résolvent plus de 90 % des problèmes de 429 sans modifier aucune limite.

Quelle est la différence entre un 429 sur /v1/tasks et un 429 sur /v1/tasks/{taskId} ?

Le point de terminaison indique simplement ce que vous faisiez à ce moment-là — les deux partagent le même budget de débit par clé. Un 429 sur l'interface de création pointe vers un fan-out (limitez la concurrence, passez au traitement par lots) ; un 429 sur l'interface d'interrogation pointe vers une boucle d'interrogation serrée (ralentissez le rythme ou passez aux callbacks). La structure complète des requêtes/réponses est décrite dans le HiAPI Quickstart et la documentation d'authentification.

En résumé

Un 429 est un signal normal et récupérable que renvoie toute passerelle API de production. Ajoutez un backoff exponentiel, limitez la concurrence côté client, remplacez l'interrogation par des callbacks et vérifiez l'usage dans le tableau de bord. Une fois ces quatre choses en place, vous pouvez complètement oublier les 429. Cette page est la version chinoise simplifiée de l'original anglais « How to Fix HiAPI Rate Limit (429) Errors », les détails techniques restant identiques à l'original.