Passer au contenu principal
L’API Fastino utilise les codes de statut HTTP standard pour communiquer le résultat de chaque requête. Les codes de la plage 2xx indiquent un succès. Les codes de la plage 4xx indiquent un problème avec votre requête que vous pouvez corriger. Les codes de la plage 5xx indiquent un problème côté serveur.

Format des réponses d’erreur

La plupart des erreurs synchrones de l’API utilisent une enveloppe error imbriquée commune :
Les erreurs de validation utilisent la même enveloppe et ajoutent un tableau errors dans error. Chaque élément identifie le champ invalide avec location et raw_location, puis explique l’échec dans message. Certaines familles d’endpoints utilisent volontairement des formats différents :
  • Refus de facturation (402, certains 403) renvoient {"code", "message", "resolution_url"} au lieu de l’enveloppe imbriquée - voir 402 et 403 ci-dessous.
  • Réponses de préchauffage (425) incluent un en-tête Retry-After. Les corps au format OpenAI portent aussi code: "model_warming" - voir 425 ci-dessous.
  • Réponses de limitation de débit (429) ajoutent les champs code et scope au niveau supérieur à côté de detail, ainsi que les en-têtes X-RateLimit-Scope et X-RateLimit-Code - voir 429 ci-dessous.
  • Erreurs serveur non gérées (500) renvoient {"error", "message"} plutôt que l’enveloppe imbriquée.
  • Les requêtes vers /v1/messages avec un en-tête anthropic-version reçoivent une enveloppe au format Anthropic {"type": "error", "error": {"type", "message"}}.

Échecs des futures interactifs

Un HTTP 4xx signifie que le serveur a rejeté un appel interactif avant de le mettre en file. Une réponse de mise en file réussie renvoie un future_id. Interrogez ce future jusqu’à l’état completed, failed ou cancelled. Un future en file dont le statut est status: "failed" peut inclure error.message ; traitez error.category comme une chaîne opaque plutôt que comme une règle de nouvelle tentative.

Codes de statut

400 - Requête incorrecte

La requête elle-même est mal formée - JSON invalide, ou un paramètre de requête/de chemin du mauvais type. Les endpoints d’inférence renvoient aussi 400 lorsqu’une entrée passe la validation du schéma mais ne peut pas être traitée, par exemple un prompt GLiDE plus long que la fenêtre de contexte ou une image hors des limites d’image GLiDE. Comment corriger : Vérifiez que le corps de votre requête est un JSON valide et que les paramètres de requête/de chemin correspondent aux types documentés dans la référence de l’endpoint. Pour une entrée d’inférence, lisez error.message et corrigez l’entrée qu’il désigne.

Erreurs liées aux images GLiDE

POST /v1/systemone renvoie ces réponses 400 pour une image dans state. Chacune utilise l’enveloppe imbriquée avec "type": "invalid_request_error" et "code": null : identifiez donc l’erreur par error.message :
Une partie image_url sans image_url.url échoue plutôt à la validation du schéma et renvoie 422 avec image_url parts require an image_url.url.

401 - Non autorisé

Votre requête ne contenait pas de clé API valide, la clé a été révoquée, ou votre compte a été bloqué pour raison de facturation ou d’examen antifraude. Comment corriger : Vérifiez que l’en-tête X-API-Key est présent et contient votre clé actuelle. Si vous avez récemment révoqué la clé, générez-en une nouvelle dans Settings → API Keys. Si votre compte est bloqué, contactez support@fastino.ai. Consultez Authentification pour les instructions de configuration.

402 - Paiement requis

Une réponse 402 signifie que votre compte n’a plus de crédits utilisables ou qu’une action de facturation est requise avant de pouvoir exécuter l’inférence. Tous les appels API échoueront jusqu’à ce que vous ajoutiez des crédits ou passiez à un plan supérieur. Rendez-vous dans Settings → Billing ou consultez Plans & tarifs pour résoudre cela.
Votre compte ne dispose pas de crédits suffisants pour effectuer la requête. Le champ code du corps de la réponse vous indique le cas concerné - le plus souvent out_of_credits (vos crédits inclus sont épuisés et il n’y a pas de solde payé utilisable) ou funding_required (votre compte n’a jamais été approvisionné). spend_limit_reached signifie qu’une limite de dépense quotidienne ou mensuelle de votre équipe ou projet a été atteinte, et billing_required signifie qu’une action de facturation est nécessaire avant de lancer l’inférence. Comment corriger : Connectez-vous à Fastino, allez dans Settings → Billing, et rechargez votre solde ou passez à un plan supérieur. Pour spend_limit_reached, augmentez la limite dans les paramètres de facturation ou attendez la réinitialisation de la période. Consultez Plans & tarifs pour les détails sur les plans et les crédits.

403 - Interdit

Votre équipe a atteint le plafond mensuel maximum de dépassement de son plan (code: "credit_ceiling_reached"), ou votre compte doit disposer d’un moyen de paiement vérifié avant de pouvoir exécuter l’inférence (code: "card_required"). Comment corriger : Pour un refus lié au plafond de dépenses, passez à un plan supérieur dans Settings → Billing pour augmenter le plafond. Pour un refus lié à la vérification de la carte, ajoutez un moyen de paiement valide. Les deux réponses incluent une resolution_url pointant directement vers la page permettant de résoudre le problème.

404 - Introuvable

La ressource que vous avez demandée n’existe pas. Cela peut se produire lorsqu’un nom de jeu de données, un ID de tâche d’entraînement, un ID d’évaluation, un ID de projet ou un ID de modèle est mal orthographié ou a été supprimé. Comment corriger : Vérifiez à nouveau l’ID ou le nom dans le chemin ou le corps de la requête. Utilisez l’endpoint de liste GET correspondant (par exemple GET /v1/training/jobs, GET /v1/base-models) pour confirmer que la ressource existe.

409 - Conflit

Le modèle existe dans le catalogue mais n’est pas actuellement servable - par exemple, un modèle de base uniquement destiné à l’entraînement demandé pour de l’inférence directe, ou un déploiement à la demande qui n’a pas fini d’être provisionné après la fin d’une tâche d’entraînement. Comment corriger : Vérifiez supports_inference et supports_on_demand_inference pour le modèle via GET /v1/base-models, ou réessayez une fois le déploiement provisionné.

413 - Charge utile trop volumineuse

Le corps de la requête - typiquement un envoi de fichier pour une évaluation ou un jeu de données - dépasse la limite de taille de l’endpoint. Comment corriger : Consultez la référence de l’endpoint pour connaître sa limite de taille d’envoi et découpez ou compressez la charge utile avant de réessayer.

422 - Entité non traitable

Le corps de la requête a échoué à la validation. Un champ requis est manquant, un champ a le mauvais type, ou une valeur est hors de la plage acceptée. Comment corriger : Consultez error.message et les éléments de error.errors pour connaître le champ précis en cause. Les causes courantes incluent :
  • Omission de model ou de type dans POST /v1/training/jobs
  • Envoi de moins d’1 ou plus de 1 000 chaînes dans le tableau inputs pour les endpoints label-existing

425 - Trop tôt

Le modèle est temporairement en cours de préchauffage et n’est pas encore prêt à servir de l’inférence. Cela est attendu lors de la première requête après une période sans trafic ou vers un déploiement à la demande fraîchement provisionné, et ne signifie pas que votre requête est incorrecte. La durée du préchauffage dépend du modèle : une requête peut donc renvoyer 425 plusieurs fois avant de réussir. La plupart des endpoints renvoient un corps au format OpenAI avec code: "model_warming" :
Les requêtes vers /v1/messages portant un en-tête anthropic-version reçoivent à la place un corps au format Anthropic, sans champ code :
Comment corriger : Attendez Retry-After secondes (30 si l’en-tête est absent) et renvoyez la même requête, avec un nombre limité de nouvelles tentatives. Chaque exemple réessaie au plus 5 fois, définit un délai client de 300 secondes et s’arrête sur toute autre réponse non 2xx. La même boucle fonctionne pour /v1/systemone ; changez l’URL et le corps de la requête.
Avec un SDK, consultez Nouvelles tentatives et préchauffage pour savoir quelles réponses réessayer et comment appliquer un backoff.

429 - Trop de requêtes

Vous avez dépassé la limite de débit de requêtes pour cet endpoint. La réponse inclut un en-tête Retry-After, ainsi que les en-têtes X-RateLimit-Scope et X-RateLimit-Code identifiant la limite atteinte - le corps JSON contient des champs code et scope correspondants à côté de detail. Comment corriger : Respectez la valeur Retry-After et attendez avant de réessayer. Consultez Nouvelles tentatives et préchauffage pour un modèle de nouvelles tentatives. Notez que les refus liés aux crédits et au dépassement renvoient 402/403, et non 429.

451 - Indisponible pour des raisons légales

Le modèle demandé n’est pas disponible pour votre compte en raison de restrictions liées au contrôle des exportations ou aux sanctions dans votre région. Comment corriger : Si vous estimez que votre accès a été restreint à tort, contactez le support.

500 - Erreur interne du serveur

Une erreur inattendue s’est produite sur les serveurs de Fastino. Elle n’est pas causée par votre requête. Le corps utilise les champs error et message plutôt que detail :
Comment corriger : Attendez un instant et réessayez. Si l’erreur persiste, consultez status.fastino.ai pour l’état des services en direct ou contactez le support.

503 - Service indisponible

Une dépendance nécessaire à la requête - vérification de facturation, ou endpoint de statut/métriques d’un fournisseur - est temporairement indisponible. Comment corriger : Attendez un instant et réessayez. Si l’erreur persiste, consultez status.fastino.ai pour l’état des services en direct ou contactez le support.

529 - Surchargé (endpoint compatible Anthropic uniquement)

POST /v1/messages reproduit la propre réponse overloaded_error d’Anthropic lorsque la capacité amont de Claude est temporairement saturée. Comment corriger : Réessayez avec un backoff, comme vous le feriez pour un 429 ou un 503.