API Claude Opus 5.5 : première requête et erreurs 400

Une clé API valide ne suffit pas toujours : votre première requête vers Claude Opus 5.5 peut renvoyer 400 Bad Request. Vérifiez l’identifiant exact du modèle, les champs obligatoires de Messages comme max_tokens, les réglages de thinking et tool_choice. L’absence de max_tokens est une erreur générale de validation de Messages, pas une nouvelle restriction d’Opus 5.5 ; les changements propres au modèle concernent notamment thinking et le choix d’outil forcé.

Ce guide commence par une requête minimale, puis vérifie les erreurs 400 dans l’ordre. Consultez la référence Messages API pour les champs obligatoires et le guide de migration d’Anthropic pour les changements propres à Opus 5.5. Exécutez une fois la requête minimale pour vérifier la connexion et la route du modèle ; en cas d’échec, utilisez le corps d’erreur renvoyé. Avant de router claude-opus-5-5 via BetterToken, vérifiez le jour de la publication ou du déploiement que cet identifiant figure dans le catalogue actuel.

1. Vérifiez d’abord la clé API, la Base URL et le Model ID

Une première requête n’exige que trois valeurs : votre propre clé API BetterToken, la Base URL Anthropic-compatible et un Model ID actuellement disponible.

1. Connectez-vous à BetterToken Workspace et créez une clé API dans votre propre compte. Stockez-la dans un gestionnaire de secrets ou un fichier d’environnement local ; ne la validez jamais dans Git et ne la collez pas dans un message de support.
2. Ouvrez le catalogue actuel des modèles et des prix et confirmez la disponibilité exacte de claude-opus-5-5. Anthropic le définit comme un identifiant fixe sans suffixe de date, mais la disponibilité et les tarifs BetterToken restent dynamiques.
3. Passez la clé par une variable d’environnement au lieu de l’inscrire en dur dans l’application.

Vous avez besoin de votre propre compte BetterToken pour créer une clé API. Créer un compte BetterToken

Pour les étapes dans l’interface, consultez le BetterToken Quickstart.

2. Gardez /v1 hors de la Base URL, mais dans le chemin HTTP direct

Utilisez https://bettertoken.ai comme Base URL d’un SDK Anthropic, et https://www.bettertoken.ai/v1/messages pour une requête Messages HTTP directe.

https://bettertoken.ai

N’utilisez pas /messages comme Base URL et n’ajoutez pas /v1/messages deux fois si le SDK complète déjà le chemin de ressource. Définissez les trois valeurs dans le shell courant :

read -rs ANTHROPIC_API_KEY && export ANTHROPIC_API_KEY
export ANTHROPIC_BASE_URL="https://bettertoken.ai"
export CLAUDE_MODEL_ID="claude-opus-5-5"

Exécutez d’abord uniquement la première ligne. Le terminal attend alors une saisie masquée : saisissez ou collez la clé API, puis appuyez sur Entrée ; aucun caractère ne s’affiche. La clé est exportée uniquement dans le shell courant et l’historique conserve la commande read, pas le secret. N’ajoutez pas la clé à la ligne de commande.

claude-opus-5-5 est le Model ID documenté par Anthropic pour Claude Platform. Si le catalogue BetterToken actuel n’affiche pas exactement cet ID, arrêtez-vous et vérifiez sa disponibilité au lieu d’inventer un alias.

3. Envoyez d’abord une requête minimale

Omettez tools, tool_choice et thinking lors du premier test afin que les options avancées ne masquent pas un problème de connexion élémentaire.

curl --fail-with-body "$ANTHROPIC_BASE_URL/v1/messages" \
  -H "x-api-key: $ANTHROPIC_API_KEY" \
  -H "anthropic-version: 2023-06-01" \
  -H "content-type: application/json" \
  -d "{
    \"model\": \"$CLAUDE_MODEL_ID\",
    \"max_tokens\": 4096,
    \"messages\": [
      {\"role\": \"user\", \"content\": \"Répondez uniquement : pong\"}
    ]
  }"

Cette requête emploie l’identifiant exact, fournit un max_tokens positif, omet thinking et n’impose aucun appel d’outil. L’exemple fixe max_tokens à 4096, comme l’exemple de migration d’Anthropic, afin de laisser davantage de place à l’adaptive thinking et à la réponse courte. Considérez cette valeur comme un point de départ de diagnostic, et non comme une garantie testée ou une recommandation de production ; en production, adaptez-la à la réponse attendue, à l’effort, au coût et à la latence.

--fail-with-body conserve le corps lorsque le serveur renvoie HTTP 4xx ou 5xx. Supprimez la clé API, les prompts complets, la sortie du modèle et les autres données sensibles avant de partager des logs.

4. Ne supposez pas que content[0] contient du texte

HTTP 200 avec un type de premier niveau égal à message signifie que l’endpoint a accepté et traité la requête. Pour ce test de réponse courte, un bloc texte confirme que la génération du contenu est terminée ; adaptive thinking et le texte partagent max_tokens, si bien qu’une réponse valide peut épuiser la limite avant l’apparition du texte.

Vérifiez les éléments suivants :

• le type de premier niveau vaut message et le champ model correspond au modèle demandé ;
• lorsque le test court se termine normalement, stop_reason vaut end_turn et le tableau content contient au moins un bloc dont le type vaut text ;
• si stop_reason vaut max_tokens, la réponse est valide mais tronquée : augmentez max_tokens et recommencez ; si vous avez explicitement choisi un effort élevé sans avoir besoin d’un raisonnement profond, vous pouvez aussi le réduire ;
• si aucun bloc texte n’apparaît et que stop_reason n’est pas max_tokens, conservez la réponse complète et diagnostiquez cette raison d’arrêt avant de changer la clé ou la Base URL ; l’absence de texte ne prouve pas à elle seule un échec de connexion ;
• votre parseur sélectionne les blocs par type au lieu de lire systématiquement content[0].text ;
• usage contient les Token d’entrée et de sortie ;
• BetterToken Dashboard affiche une requête à l’heure attendue avec son modèle, son statut, ses input/output/cache Token et son coût.

La référence officielle Anthropic Messages API décrit cette structure, et le guide des stop_reason explique comment traiter les réponses tronquées. Le Dashboard permet de rapprocher la requête et l’usage ; ne le présentez pas comme un stockage garanti du prompt ou de la réponse complets.

5. Vérifiez les erreurs générales de Messages et les changements d’Opus 5.5

La requête utilise encore un ancien nom de modèle

Remplacez un ancien ID ou un alias daté supposé par claude-opus-5-5. Anthropic le définit comme un identifiant fixe sans suffixe de date. Les plateformes cloud peuvent utiliser leurs propres IDs ; cet exemple Anthropic-compatible BetterToken doit reprendre l’ID exact du catalogue BetterToken actuel.

max_tokens est absent

Ajoutez un max_tokens positif à chaque requête Messages. Un champ absent est une erreur générale de validation de Messages API, pas un changement lié à la migration vers Opus 5.5. Il plafonne toute la sortie, thinking et texte final compris. Même un smoke test doit laisser de la place aux deux ; si stop_reason vaut max_tokens, augmentez la limite et recommencez au lieu de conclure à un échec de connexion.

Le payload désactive thinking ou fixe un budget manuel

La correction la plus simple consiste à supprimer entièrement le champ thinking. Opus 5.5 utilise toujours adaptive thinking. Le guide de migration Anthropic indique que ces deux anciennes formes sont rejetées avec 400 :

{"thinking": {"type": "disabled"}}

{"thinking": {"type": "enabled", "budget_tokens": 10000}}

Si vous devez renseigner le champ, utilisez {"thinking": {"type": "adaptive"}}. Réglez la profondeur avec output_config.effort ; les niveaux acceptés sont low, medium, high, xhigh et max, avec medium par défaut. La requête minimale n’a besoin d’aucun de ces champs.

Le payload force tool_choice

N’utilisez que {"type": "auto"} ou {"type": "none"} pour tool_choice. Opus 5.5 rejette {"type": "any"} et {"type": "tool", "name": "..."}. Dans un workflow avec outils, laissez le modèle choisir en mode auto, précisez dans le prompt quand utiliser l’outil et validez chaque schéma avant d’activer strict tool use.

6. Pour les autres statuts, lisez le corps avant de modifier la requête

Statut	À vérifier d’abord	À éviter
400	JSON valide ; model, max_tokens, messages, paramètres thinking et tool_choice	Changer la clé au hasard ou répéter le même payload invalide
401 / 403	Clé complète, bon compte ou groupe de clés, bonne Base URL	Envoyer la clé complète au support
404	Un appel HTTP direct doit utiliser /v1/messages	Considérer /messages comme la route complète
429	Délai conseillé, solde, limites et historique des requêtes	Réessayer en boucle sans pause

Nettoyez les anciennes variables d’un autre fournisseur avant de reconfigurer le shell :

unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID

Après une correction, répétez la même requête minimale. Modifier simultanément le modèle, l’endpoint, le prompt et les paramètres avancés empêche d’identifier ce qui a vraiment résolu le problème.

7. Distinguez le tarif Anthropic du prix BetterToken actuel

La page de lancement Anthropic du 22 septembre 2026 indiquait pour Claude Platform $4 par million d’Input Token, $20 par million d’Output Token, $0.20 pour les cache reads et $5 pour les cache writes. Ce sont les tarifs de plateforme publiés officiellement par Anthropic au lancement. Le prix BetterToken est dynamique : consultez la page actuelle et vérifiez une petite requête dans votre propre enregistrement du Dashboard.

Les thinking Token sont facturés comme des Output Token, et max_tokens couvre thinking plus le texte final. Une charge migrée depuis une configuration qui désactivait thinking peut donc avoir un autre profil de sortie malgré un prompt identique. Avant la production, consultez la page de prix BetterToken actuelle et rapprochez une petite requête de son enregistrement dans le Dashboard.

Avant de passer à un SDK, au streaming ou au trafic de production, revérifiez le Model ID, gardez la clé hors du code, dimensionnez max_tokens, lisez le contenu par type de bloc, évitez forced tool choice et conservez un corps d’erreur expurgé pour le diagnostic. Poursuivez avec la BetterToken API Reference et le guide officiel de migration Opus 5.5.