Codes d’erreur API
Formes d’erreur, codes de statut et gestion dans le SDK TypeScript de l’API System One.
Utilisez cette référence pour traiter les erreurs de l’API HTTP et des endpoints de console, ou pour intégrer le SDK System One. Le Playground affiche un message destiné à l’utilisateur ; une application doit classer les erreurs à partir des en-têtes de réponse documentés.
Prêt pour les questions
Comment fonctionne la gestion des erreurs de l’API System One ? Une enveloppe d’erreur cohérente et des codes de statut HTTP ; des erreurs typées dans le SDK TypeScript ; et des reprises avec des clés d’idempotence lorsque c’est approprié.
Ce qu’il faut conserver
Conservez le statut HTTP, X-System-One-Error-Code, X-Request-Id et l’heure de la requête. Utilisez le code d’erreur de l’en-tête pour décider quoi faire, plutôt que de comparer des formulations de message ou de supposer que tous les corps d’erreur ont la même structure. Ne journalisez pas les clés d’API, les en-têtes d’autorisation ni le contenu sensible des requêtes.
Identifier la source de l’erreur
Lisez X-System-One-Error-Source avec X-System-One-Error-Code. La valeur upstream signifie qu’une erreur JSON valide du service de modèle conserve son statut HTTP 400–599 et son corps d’origine ; ce corps peut être un objet, un tableau, une chaîne, un autre scalaire JSON ou null. La valeur platform identifie les erreurs System One et les remplacements de sécurité.
L’en-tête de classification est stable : HTTP 429/529 devient provider_busy, 400/422 devient provider_rejected_request, et les autres pannes amont deviennent provider_unavailable. Un upstream en 401 ou 403 reste 401 ou 403 ; cela ne signifie pas que votre session System One a expiré.
Enveloppe d’erreur System One
{
"error": {
"code": "rate_limit_exceeded",
"message": "Too many requests. Retry after the indicated delay.",
"request_id": "platform-request-id"
},
"request_id": "platform-request-id"
}Les valeurs sont illustratives. Pour le support et la comptabilité, lisez l’identifiant de requête dans X-Request-Id, pas dans un champ arbitraire du corps.
Clé et problèmes de requête
| HTTP | Code | Que faire |
|---|---|---|
| 400 | invalid_json | Envoyez du JSON UTF-8 valide sans clés d’objet dupliquées. |
| 401 | invalid_api_key | Vérifiez la clé Bearer ; créez-en une nouvelle si elle a été révoquée ou perdue. |
| 401 | unauthorized | Cet endpoint exige un compte authentifié ; connectez-vous. |
| 403 | account_disabled | Contactez le support au sujet de votre compte. |
| 404 | not_found | Vérifiez l’origine de l’application et le chemin documenté. |
| 405 | method_not_allowed | Utilisez la méthode documentée de l’endpoint. |
| 413 | request_too_large | Le corps dépasse la limite du modèle ou de l’endpoint. |
| 415 | unsupported_media_type | Envoyez Content-Type: application/json. |
| 422 | invalid_request | Corrigez le champ indiqué et les limites du modèle sélectionné. |
| 422 | unsupported_model | Copiez un identifiant courant depuis la liste des modèles. |
| 422 | invalid_idempotency_key | Respectez le format de clé d’opération. |
Solde, limites et requêtes répétées
| HTTP | Code | Que faire |
|---|---|---|
| 402 | insufficient_credits | Vérifiez votre solde ; ajoutez des crédits ou réduisez la taille ou le nombre de questions. |
| 409 | idempotency_conflict | La clé a été utilisée avec une autre requête ; restaurez le corps d’origine ou utilisez une nouvelle clé. |
| 409 | request_in_progress | Attendez le Retry-After, puis réessayez avec la même clé et le même corps. |
| 409 | idempotency_failed | La tentative initiale a échoué et ses crédits ont été restitués ; une nouvelle tentative délibérée exige une nouvelle clé. |
| 409 | request_expired | L’opération s’est terminée avant la fin et ses crédits ont été restitués ; vérifiez son enregistrement. |
| 410 | idempotency_expired | La réponse d’origine n’est plus disponible pour rejeu ; vérifiez l’opération d’origine. |
| 429 | rate_limit_exceeded | Attendez le Retry-After ; les clés d’API et le Playground partagent la limite du compte. |
Problèmes de service
| HTTP | Code | Que faire |
|---|---|---|
| 429 / 529 | provider_busy | Le service de modèle est occupé ; respectez Retry-After et vérifiez le résultat enregistré. |
| 400 / 422 | provider_rejected_request | Relisez la requête et les exigences du modèle sélectionné. |
| 502 ou autre 4xx/5xx | provider_unavailable | La requête au modèle n’a pas pu aboutir ; vérifiez le résultat et contactez le support si cela persiste. |
| 502 | invalid_provider_response | Le modèle a renvoyé une réponse invalide, non JSON, trop volumineuse ou une redirection. |
| 504 | provider_timeout | Le délai de 20 secondes du modèle, en-têtes et corps compris, est expiré. |
| 499 | request_cancelled | La requête a été annulée ; vérifiez son enregistrement. |
| 503 | provider_not_configured, provider_configuration_error | Le service a besoin d’une intervention ; contactez le support. |
| 503 | model_catalog_unavailable | Le catalogue courant n’a pas pu être chargé ; réessayez plus tard. |
| 503 | request_reconciliation_pending | Le débit de la requête n’est pas encore réglé ; conservez son identifiant. |
| 501 | model_listing_not_supported | La liste des modèles n’est pas disponible via cette connexion. |
| 500 | internal_error | Conservez l’identifiant de requête et vérifiez l’opération d’origine. |
Vérifier les débits avant de réessayer
Les évaluations échouées ordinaires restituent les crédits débités pour cette tentative. X-System-One-Credits: 0 confirme l’absence de débit retenu pour la tentative. Si le rapprochement immédiat ne peut pas aboutir, le service renvoie request_reconciliation_pending et omet cet en-tête. Un en-tête de débit absent ne signifie pas zéro. Consultez Facturation & crédits et les enregistrements d’usage de votre console.
Un délai dépassé ou une connexion perdue dans votre outil ne prouve pas l’échec de l’opération. Reprenez-la avec la même clé d’opération et le même corps.
Traitement des erreurs dans le SDK
Le SDK @system-one-ai/core@0.8.0 exporte APIError avec statusCode, requestId et retryAfterMs, mais pas le corps complet de l’erreur ni les en-têtes de classification. Utilisez Fetch lorsqu’une intégration doit distinguer les différents codes 409. Les politiques de reprise des clients sont distinctes du service, qui ne réessaie pas automatiquement l’inférence du modèle. Après une réponse incertaine, reprenez avec la clé et le corps conservés ; après un échec enregistré et restitué, utilisez une nouvelle clé uniquement pour une nouvelle tentative délibérée. Voir Clé d’idempotence.
Pour les erreurs non résolues, écrivez à support@system-one.dev avec l’identifiant de requête, l’heure, le statut et le code d’erreur. N’envoyez jamais la clé d’API ni le contenu soumis.