> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fastino.ai/llms.txt
> Use this file to discover all available pages before exploring further.
> ## Agent Instructions
> Use https://docs.fastino.ai/llms.txt to discover and navigate pages. Use https://docs.fastino.ai/llms-full.txt when you need the complete documentation corpus. Use https://docs.fastino.ai/openapi.json as the source of truth for customer-facing routes. For GLiDE decision inference, call POST https://api.fastino.ai/v1/systemone with model fastino/GLiDE. Do not infer undocumented routes. Read API keys from FASTINO_API_KEY and never embed credentials in code, logs, or reports.
# Codes d'erreur et formats de réponse de l'API Fastino
> Tous les codes 4xx et 5xx renvoyés par l'API Fastino, le format JSON par famille et comment résoudre les erreurs de facturation, de débit et de validation.
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 réponses d'erreur renvoient un corps JSON avec un champ `detail` :
```json theme={null}
{
"detail": "..."
}
```
Quelques familles de réponses utilisent une forme différente :
* **Refus de facturation** (`402`, certains `403`) renvoient `{"code", "message", "resolution_url"}` au lieu de `detail` - voir [402](#402-paiement-requis) et [403](#403-interdit) 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](#425-trop-tôt) ci-dessous.
* **Réponses de limitation de débit** (`429`) ajoutent des champs `code` et `scope` à côté de `detail`, ainsi que les en-têtes `X-RateLimit-Scope` et `X-RateLimit-Code` - voir [429](#429-trop-de-requêtes) ci-dessous.
* **Erreurs serveur non gérées** (`500`) renvoient `{"error", "message"}` plutôt que `detail`.
* Les requêtes vers les endpoints compatibles OpenAI (`/v1/chat/completions`, `/v1/responses`) reçoivent une enveloppe au format OpenAI `{"error": {"code", "type", "param", "message"}}`, et les requêtes portant un en-tête `anthropic-version` reçoivent une enveloppe au format Anthropic `{"type": "error", "error": {"type", "message"}}` au lieu des formes génériques ci-dessus.
## 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.
**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.
***
### 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@pioneer.ai](mailto:support@pioneer.ai). Consultez [Authentification](/fr/authentication) 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](/fr/pricing) 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 `direct_model_requires_credits` (appeler directement un modèle pris en charge nécessite un solde de crédits payé).
**Comment corriger :** Connectez-vous à [Fastino](https://agent.fastino.ai), allez dans **Settings** → **Billing**, et rechargez votre solde ou passez à un plan supérieur. Consultez [Limites de crédits et plafond de dépassement](/fr/api-reference/rate-limits) pour comprendre le fonctionnement des limites de crédits et de la facturation en dépassement.
***
### 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 le `message` d'erreur pour connaître le champ précis en cause. Les causes courantes incluent :
* Omission de `base_model` 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
```json theme={null}
{
"detail": "For 'POST /v1/training-jobs', ...",
"errors": [...]
}
```
***
### 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"` :
```json theme={null}
{
"error": {
"message": "...",
"type": "invalid_request_error",
"param": null,
"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` :
```json theme={null}
{
"type": "error",
"error": {
"type": "invalid_request_error",
"message": "..."
}
}
```
| En-tête | Valeur |
| - | - |
| `Retry-After` | Nombre de secondes à attendre avant la prochaine tentative. C'est un délai de nouvelle tentative, pas une garantie que le modèle sera prêt. |
| `x-should-retry` | `true` sur les réponses au format OpenAI : les SDK OpenAI réessaient donc automatiquement. `false` sur les réponses au format Anthropic : les SDK Anthropic ne réessaient pas, gérez-les vous-même. |
**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.
```bash cURL theme={null}
for attempt in 0 1 2 3 4 5; do
http_code=$(curl -sS --max-time 300 -o response.json -D headers.txt -w "%{http_code}" \
https://api.fastino.ai/v1/chat/completions \
-H "Authorization: Bearer $FASTINO_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "fastino/gliner2.5-multi-v1",
"messages": [{ "role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino." }],
"schema": { "entities": ["organization", "product"] }
}')
[ "$http_code" = "425" ] && [ "$attempt" -lt 5 ] || break
delay=$(awk 'tolower($1) == "retry-after:" && $2 + 0 > 0 { print $2 + 0 }' headers.txt)
sleep "${delay:-30}"
done
if [ "$http_code" -ge 200 ] && [ "$http_code" -lt 300 ]; then
cat response.json
else
echo "Request failed with HTTP $http_code: $(cat response.json)" >&2
fi
```
```python Python theme={null}
import os
import time
import requests
MAX_RETRIES = 5
for attempt in range(MAX_RETRIES + 1):
response = requests.post(
"https://api.fastino.ai/v1/chat/completions",
headers={"Authorization": f"Bearer {os.environ['FASTINO_API_KEY']}"},
json={
"model": "fastino/gliner2.5-multi-v1",
"messages": [
{"role": "user", "content": "Apple announced the MacBook Pro at WWDC in Cupertino."}
],
"schema": {"entities": ["organization", "product"]},
},
timeout=300,
)
if response.status_code != 425 or attempt == MAX_RETRIES:
break
retry_after = response.headers.get("Retry-After", "")
time.sleep(int(retry_after) if retry_after.isdigit() else 30)
if not 200 <= response.status_code < 300:
raise RuntimeError(f"Request failed: {response.status_code} {response.text}")
print(response.json()["choices"][0]["message"]["content"])
```
```javascript JavaScript theme={null}
const MAX_RETRIES = 5;
let response;
for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
response = await fetch("https://api.fastino.ai/v1/chat/completions", {
method: "POST",
headers: {
Authorization: `Bearer ${process.env.FASTINO_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
model: "fastino/gliner2.5-multi-v1",
messages: [{ role: "user", content: "Apple announced the MacBook Pro at WWDC in Cupertino." }],
schema: { entities: ["organization", "product"] },
}),
signal: AbortSignal.timeout(300_000),
});
if (response.status !== 425 || attempt === MAX_RETRIES) break;
const retryAfter = Number(response.headers.get("Retry-After"));
await new Promise((resolve) => setTimeout(resolve, (retryAfter || 30) * 1000));
}
if (!response.ok) {
throw new Error(`Request failed: ${response.status} ${await response.text()}`);
}
const completion = await response.json();
console.log(completion.choices[0].message.content);
```
Avec un SDK, consultez [Nouvelles tentatives et préchauffage](/fr/troubleshooting/retries) 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 [Limites de débit](/fr/api-reference/rate-limits) pour les limites par endpoint et un modèle de code pour les nouvelles tentatives. Notez que les refus liés aux crédits et au dépassement renvoient `402`/`403`, et non `429` - voir [Limites de crédits et plafond de dépassement](/fr/api-reference/rate-limits).
***
### 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 :** Consultez la [FAQ](/fr/faq) pour la liste actuelle des régions restreintes et les politiques spécifiques à chaque fournisseur. 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` :
```json theme={null}
{
"error": "Internal server error",
"message": "..."
}
```
**Comment corriger :** Attendez un instant et réessayez. Si l'erreur persiste, consultez [status.pioneer.ai](https://status.pioneer.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.pioneer.ai](https://status.pioneer.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`.
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.