Claude Opus 5.5 API: erste Anfrage und 400-Fehler beheben

Auch mit einem gültigen API Key kann die erste Anfrage an Claude Opus 5.5 mit 400 Bad Request enden. Prüfen Sie die genaue Model ID, Pflichtfelder der Messages API wie max_tokens, thinking-Einstellungen und tool_choice. Ein fehlendes max_tokens ist ein allgemeiner Validierungsfehler der Messages API, keine neue Beschränkung von Opus 5.5; modellspezifisch ändern sich insbesondere thinking und die erzwungene Werkzeugauswahl.

Diese Anleitung beginnt mit einem kleinen Request und prüft danach 400-Fehler der Reihe nach. Für Pflichtfelder gilt die Messages-API-Referenz; für modellspezifische Änderungen gilt der Opus-5.5-Migrationsleitfaden von Anthropic. Führen Sie den minimalen Request einmal aus, um Verbindung und Modellroute zu prüfen; falls er fehlschlägt, nutzen Sie den zurückgegebenen Fehler-Body. Prüfen Sie außerdem am Veröffentlichungs- oder Einsatztag, ob claude-opus-5-5 im aktuellen BetterToken-Katalog verfügbar ist.

1. Prüfen Sie zuerst API Key, Base URL und Model ID

Für den ersten Request brauchen Sie nur drei Werte: Ihren eigenen BetterToken API Key, die Anthropic-compatible Base URL und eine aktuell verfügbare Model ID.

1. Melden Sie sich im BetterToken Workspace an und erstellen Sie in Ihrem eigenen Konto einen API Key. Speichern Sie ihn in einem Secret Manager oder einer lokalen Umgebungsdatei; niemals in Git oder einer Support-Nachricht.
2. Öffnen Sie den aktuellen Modell- und Preiskatalog und prüfen Sie, ob die exakte ID claude-opus-5-5 verfügbar ist. Anthropic definiert sie als feste Model ID ohne Datumssuffix, doch Verfügbarkeit und Preise bei BetterToken sind dynamisch.
3. Übergeben Sie den Key als Umgebungsvariable, statt ihn im Anwendungscode fest einzutragen.

Zum Erstellen eines API Keys benötigen Sie ein eigenes BetterToken-Konto. BetterToken-Konto erstellen

Die Schritte in der Oberfläche zeigt der BetterToken Quickstart.

2. Lassen Sie /v1 aus der Base URL, aber im direkten Request-Pfad

Für ein Anthropic SDK lautet die Base URL https://bettertoken.ai; für einen direkten Messages-Request lautet die vollständige URL https://www.bettertoken.ai/v1/messages.

https://bettertoken.ai

Verwenden Sie /messages nicht als Base URL und hängen Sie /v1/messages nicht erneut an, wenn das SDK den Ressourcenpfad bereits ergänzt. Setzen Sie die drei Werte in der aktuellen Shell:

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

Führen Sie zunächst nur die erste Zeile aus. Das Terminal wartet dann auf eine verdeckte Eingabe: Geben Sie den API Key ein oder fügen Sie ihn ein und drücken Sie Enter; es werden keine Zeichen angezeigt. Der Schlüssel wird nur in die aktuelle Shell exportiert, während der Verlauf den read-Befehl statt des Geheimnisses speichert. Hängen Sie den Schlüssel nicht an die Befehlszeile an.

claude-opus-5-5 ist die von Anthropic für die Claude Platform dokumentierte Model ID. Wenn der aktuelle BetterToken-Katalog diese exakte ID nicht zeigt, prüfen Sie die Verfügbarkeit, statt einen Alias zu erraten.

3. Senden Sie zuerst einen minimalen Request

Lassen Sie tools, tool_choice und thinking beim ersten Test weg, damit erweiterte Optionen kein grundlegendes Verbindungsproblem verdecken.

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\": \"Antworte nur mit: pong\"}
    ]
  }"

Der Request verwendet die exakte Model ID, enthält ein positives max_tokens, lässt thinking weg und erzwingt keinen Tool-Aufruf. Das Beispiel setzt max_tokens auf 4096, wie im Anthropic-Migrationsbeispiel, damit adaptive thinking und die kurze Antwort mehr gemeinsamen Spielraum haben. Dieser Wert ist ein Ausgangspunkt für die Diagnose, kein hier getesteter Garantiewert und keine Produktionsvorgabe; für Produktion muss er zur erwarteten Antwort, zum Effort, zu den Kosten und zum Latenzziel passen.

--fail-with-body behält den Response-Body bei HTTP 4xx oder 5xx bei. Entfernen Sie API Key, vollständige Prompts, Modellausgaben und andere sensible Daten, bevor Sie Logs weitergeben.

4. Nehmen Sie nicht an, dass content[0] Text enthält

HTTP 200 mit einem obersten type von message bedeutet, dass der Endpoint den Request angenommen und verarbeitet hat. Bei diesem Kurzantwort-Test bestätigt ein Textblock, dass die Inhaltsgenerierung abgeschlossen ist; adaptive thinking und Antworttext teilen sich max_tokens, sodass eine gültige Antwort das Limit vor dem ersten Textblock erreichen kann.

Prüfen Sie folgende Signale:

• der oberste type ist message, und das oberste Feld model entspricht dem angefragten Modell;
• wenn der Kurztest normal endet, ist stop_reason gleich end_turn, und das Array content enthält mindestens einen Block mit type gleich text;
• ist stop_reason gleich max_tokens, ist die Antwort gültig, aber abgeschnitten: Erhöhen Sie max_tokens und wiederholen Sie den Request; bei ausdrücklich hohem Effort ohne Bedarf an tiefem Reasoning können Sie den Effort auch senken;
• fehlt ein Textblock und ist stop_reason nicht max_tokens, bewahren Sie die vollständige Antwort auf und diagnostizieren Sie diesen Stop-Grund, bevor Sie Key oder Base URL ändern; fehlender Text allein beweist keinen Verbindungsfehler;
• Ihr Parser wählt Blöcke nach type aus, statt immer content[0].text zu lesen;
• usage enthält Eingabe- und Ausgabe-Token;
• im BetterToken Dashboard erscheint zum erwarteten Zeitpunkt ein Eintrag mit Modell, Status, input/output/cache Token und Belastung.

Die offizielle Anthropic Messages API Reference beschreibt die Response-Struktur, und der Leitfaden zu stop_reason erklärt den Umgang mit abgeschnittenen Antworten. Das Dashboard dient zum Abgleich von Request und Nutzung; es sollte nicht als garantierter Speicher für den vollständigen Prompt oder die vollständige Antwort dargestellt werden.

5. 400-Fehler: allgemeine Messages-Prüfung und Änderungen bei Opus 5.5

Im Request steht noch ein älterer Modellname

Ersetzen Sie eine ältere ID oder einen erfundenen datierten Alias durch claude-opus-5-5. Anthropic definiert dies als feste ID ohne Datumssuffix. Cloud-Plattformen können eigene IDs verwenden; dieses Anthropic-compatible BetterToken-Beispiel muss die exakte ID aus dem aktuellen BetterToken-Katalog verwenden.

max_tokens fehlt

Jeder Messages-Request braucht ein positives max_tokens. Ein fehlendes Feld ist ein allgemeiner Validierungsfehler der Messages API, keine Neuerung von Opus 5.5. Es begrenzt die gesamte Ausgabe, also thinking plus finalen Text. Auch ein Smoke Test braucht Platz für beides; ist stop_reason gleich max_tokens, erhöhen Sie das Limit und wiederholen Sie den Request, statt einen Verbindungsfehler anzunehmen.

Der Payload deaktiviert thinking oder setzt ein manuelles Budget

Die einfachste Korrektur ist, das gesamte Feld thinking zu entfernen. Opus 5.5 verwendet immer adaptive thinking. Laut Anthropic-Migrationsleitfaden werden beide alten Formen mit 400 abgelehnt:

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

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

Falls ein explizites Feld nötig ist, verwenden Sie {"thinking": {"type": "adaptive"}}. Die Tiefe steuern Sie mit output_config.effort; unterstützt werden low, medium, high, xhigh und max, Standard ist medium. Der minimale Verbindungstest braucht keines dieser Felder.

Der Payload erzwingt tool_choice

Für tool_choice sind nur {"type": "auto"} und {"type": "none"} zulässig. Opus 5.5 lehnt {"type": "any"} sowie {"type": "tool", "name": "..."} ab. Lassen Sie das Modell im Modus auto wählen, erklären Sie im Prompt, wann ein Werkzeug einzusetzen ist, und prüfen Sie jedes Schema, bevor Sie strict tool use aktivieren.

6. Lesen Sie bei anderen Statuscodes zuerst den Response-Body

Status	Zuerst prüfen	Vermeiden
400	Gültiges JSON; model, max_tokens, messages, thinking-Einstellungen und tool_choice	Den Key blind austauschen oder denselben ungültigen Payload wiederholen
401 / 403	Vollständiger Key, richtiges Konto oder Key-Gruppe, korrekte Base URL	Den vollständigen Key an den Support senden
404	Ein direkter HTTP-Aufruf benötigt /v1/messages	/messages als vollständige Route behandeln
429	Retry-Hinweis im Body, Guthaben, Limits und Request-Historie	Ohne Pause in einer Schleife erneut senden

Löschen Sie veraltete Variablen eines anderen Providers, bevor Sie die Shell neu konfigurieren:

unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID

Wiederholen Sie nach der Korrektur denselben minimalen Request. Wenn Sie Modell, Endpoint, Prompt und erweiterte Parameter gleichzeitig ändern, lässt sich die wirksame Korrektur kaum erkennen.

7. Trennen Sie Anthropic-Listenpreise vom aktuellen BetterToken-Preis

Auf der Anthropic-Launchseite vom 22. September 2026 standen für die Claude Platform $4 je Million Input Token, $20 je Million Output Token, $0.20 für Cache Reads und $5 für Cache Writes. Das sind die von Anthropic offiziell veröffentlichten Plattformpreise zum Start. Der BetterToken-Preis ist dynamisch; prüfen Sie daher die aktuelle Preisseite und gleichen Sie einen kleinen eigenen Request mit dem Dashboard-Eintrag ab.

Thinking Token werden als Output Token berechnet, und max_tokens umfasst thinking plus finalen Text. Ein Workload, der zuvor thinking deaktiviert hatte, kann deshalb trotz unverändertem Prompt ein anderes Output-Token-Profil haben. Prüfen Sie vor dem Produktiveinsatz die aktuelle BetterToken-Preisseite und gleichen Sie einen kleinen Request mit dem Dashboard-Eintrag ab.

Bevor Sie zu SDK, Streaming oder Production-Traffic wechseln, prüfen Sie nochmals Model ID, Secret-Speicherung, die Größe von max_tokens, die Blockauswahl nach type, das Fehlen erzwungener Tool Choice und einen bereinigten Fehler-Body für die Diagnose. Weitere Details finden Sie in der BetterToken API Reference und im offiziellen Opus-5.5-Migrationsleitfaden.