Codes d'erreur de l'API Velqa.dev et comment les corriger
Récapitulatif des erreurs HTTP renvoyées par l'API OpenAI-compatible https://api.velqa.dev/v1, leur cause la plus fréquente et la correction à appliquer. Chaque réponse d'erreur contient un objet JSON error avec un message explicite.
Tableau des erreurs
| Code | Signification | Cause fréquente | Correction |
|---|---|---|---|
| 401 | Unauthorized | Clé absente, invalide ou révoquée ; en-tête mal formé | Vérifiez l'en-tête Authorization: Bearer sk-.... Recréez une clé dans Clés API si elle a été révoquée. |
| 402 | Payment Required | Solde / budget insuffisant : budget mensuel de la clé épuisé, ou solde Boost à zéro (audio, image, TTS) | Rechargez votre solde ou augmentez le budget de la clé. Voir Fallback Boost et Limites. |
| 403 | Forbidden | Modèle non autorisé pour votre clé ou votre plan (ex. glm-5.2 en Starter, ou un modèle Boost-only sans solde) | Vérifiez la disponibilité par plan dans Modèles. Passez à un plan supérieur ou utilisez le Recharge Boost. |
| 400 | Bad Request | Paramètres invalides : JSON mal formé, champ manquant, n ou size hors limites (images), voix inconnue (TTS) | Corrigez la requête. Pour les images : n ≤ 4, size ≤ 1024x1024. |
| 429 | Too Many Requests | Débit dépassé (RPM/TPM), ou contexte trop grand (« Trop de tokens demandes »), ou aucun slot Sandbox libre | Réessayez avec backoff. Si c'est le contexte, réduisez la fenêtre de contexte dans votre outil — voir opencode. Si c'est le Sandbox, c'est la capacité et non votre quota — voir vue d'ensemble Sandbox. Détails : Limites. |
| 404 | Not Found | Identifiant de modèle inexistant ou mal orthographié | Utilisez un model_id exact du catalogue Modèles. Ne conservez pas un identifiant retiré dans une configuration. |
Bonnes pratiques
- Lisez toujours le champ
error.message: il précise la cause exacte (modèle, paramètre, ou limite en cause). - Traitez 429 avec un backoff exponentiel ; traitez 402 en surveillant votre solde en amont.
- Un 429 « Trop de tokens demandes » n'est pas un problème de débit mais de taille de contexte : plafonnez la fenêtre de contexte de votre agent.