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. kimi-k2.6 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 demandés ») | Réessayez avec backoff. Si c'est le contexte, réduisez la fenêtre de contexte dans votre outil — voir opencode. Détails : Limites. |
| 404 | Not Found | Identifiant de modèle inexistant ou mal orthographié | Utilisez un model_id exact du catalogue Modèles. Les ids sont stables (ex. kimi-k2.6, pas kimi-k2). |
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 demandés » n'est pas un problème de débit mais de taille de contexte : plafonnez la fenêtre de contexte de votre agent.