Erreurs et limites de débit
Formats des réponses d'erreur, tableau complet des codes de statut HTTP, comportement des limites de débit et stratégie de retentative adaptée à Atlas Cloud.
Formats des réponses d'erreur
Atlas Cloud renvoie trois formats d'erreur différents selon la partie de l'API que vous appelez. Vérifiez le format avant d'écrire un parseur.
Utilisé par les points de terminaison des protocoles LLM et par ceux de génération de médias :
{
"code": 401,
"msg": "unauthorized",
"request_id": "…",
"data": null
}Chaque réponse porte un en-tête X-Request-ID. Journalisez-le — c'est le moyen le plus rapide pour le support de retracer un appel précis.
Codes de statut HTTP
| Statut | Signification | Que faire |
|---|---|---|
400 | Requête mal formée : corps illisible, model manquant, mauvais content type, en-tête de rétention invalide ou webhook_url invalide | Corrigez la requête. Le champ msg nomme le problème précis |
401 | Échec de l'authentification — clé absente, inconnue ou expirée | Vérifiez la clé. Notez qu'un chemin d'URL erroné renvoie aussi 401 : vérifiez donc également le point de terminaison |
402 | Solde insuffisant, ou quota Coding Plan épuisé | Rechargez |
403 | Le compte ou l'utilisateur n'est pas autorisé — inclut l'utilisation d'une clé Coding Plan sur un modèle qui ne l'accepte pas | Vérifiez la portée de la clé, ou contactez le support |
404 | Ressource introuvable. Pour les modèles, cela couvre aussi ceux qui ne sont pas disponibles pour votre compte | Vérifiez l'ID du modèle dans le catalogue |
413 | Le corps de la requête dépasse 50 Mo | Envoyez une URL au lieu de Base64 en ligne, ou téléversez le fichier au préalable |
429 | Limite de débit atteinte | Faites un backoff et réessayez — voir ci-dessous |
451 | Bloqué dans votre région | Non retentable |
500 | Erreur interne | Réessayez une fois, puis signalez avec l'ID de requête |
503 | Temporairement indisponible | Réessayez avec un backoff |
504 | Une requête synchrone a dépassé le délai d'attente maximum | Passez au flux asynchrone et faites du polling |
Un 401 ne signifie pas toujours que votre clé est mauvaise. La passerelle authentifie avant de router : une faute de frappe dans le chemin produit donc aussi un 401 plutôt qu'un 404. Si une clé fonctionne ailleurs, vérifiez d'abord l'URL.
Codes d'erreur au niveau de la tâche
Lorsqu'une tâche asynchrone échoue, data.error_code porte un code plateforme numérique plus précis que le statut HTTP. Par exemple, 1039 indique que l'entrée a été rejetée par la modération de contenu.
data.error contient une description lisible par un humain. Journalisez les deux, avec l'ID de prédiction.
Limites de débit
Les limites de débit s'appliquent par compte et par modèle. En dépasser une renvoie 429.
Les points de terminaison LLM et médias ne renvoient pas X-RateLimit-Limit, X-RateLimit-Remaining ni Retry-After. Vous ne pouvez pas lire votre quota restant dans les en-têtes de réponse — implémentez plutôt un backoff côté client.
Les points de terminaison de facturation /public/v1 font exception : leurs réponses 429 incluent bien Retry-After.
Si vous avez besoin de limites plus élevées pour une charge de production, contactez-nous avec votre volume de requêtes attendu et votre mélange de modèles.
Stratégie de retentative
Réessayez sur 429, 500, 503 et 504, ainsi que sur les échecs réseau. Ne réessayez pas sur 400, 401, 402, 403, 404 ni 451 — ils échoueront à l'identique.
Réessayez librement les requêtes de lecture. Soyez prudent avec les soumissions de génération : une requête arrivée en timeout peut malgré tout avoir été acceptée, et une retentative aveugle peut créer — et facturer — une seconde tâche. Préférez soumettre en asynchrone et faire du polling : ainsi une réponse perdue ne signifie jamais une tâche perdue.
import time, random, requests
RETRYABLE = {429, 500, 503, 504}
def call_with_retry(url, payload, api_key, max_attempts=4):
for attempt in range(max_attempts):
response = requests.post(
url,
json=payload,
headers={"Authorization": f"Bearer {api_key}"},
timeout=60,
)
if response.status_code not in RETRYABLE:
return response
if attempt == max_attempts - 1:
break
# Backoff exponentiel + jitter, pour éviter que tous les clients réessaient en même temps
delay = min(2 ** attempt, 30) * (0.5 + random.random() / 2)
time.sleep(delay)
return responseErreurs en streaming
Lorsqu'une requête en streaming échoue avant l'ouverture du flux, vous recevez une erreur HTTP normale. Une fois le flux démarré, la connexion reste ouverte et l'erreur arrive sous forme d'événement dans le flux — un 200 sur un appel en streaming ne garantit donc pas une réponse complète. Gérez toujours une interruption en cours de flux.
Les flux peuvent aussi contenir des lignes de commentaire SSE commençant par : en guise de signaux keep-alive. Ce ne sont pas des données et elles doivent être ignorées — la plupart des clients SSE le font pour vous, mais les parseurs faits maison souvent pas.
Obtenir de l'aide
Lorsque vous signalez un problème, incluez :
- L'en-tête
X-Request-IDde la réponse en échec - L'ID de prédiction, pour les tâches asynchrones
- L'ID exact du modèle et l'horodatage
Contactez-nous via le Support.
Voir aussi
Last updated on