Claude Opus 5.5 API: First Request and 400 Error Fixes

You may have a valid API key and still receive 400 Bad Request on your first Claude Opus 5.5 call. Check the exact model ID, required Messages API fields such as max_tokens, thinking settings, and tool_choice. A missing max_tokens is a general Messages validation error, not a new Opus 5.5 restriction; the model-specific migration changes include thinking and forced tool choice.

This guide starts with a minimal request, then checks 400 errors in order. Use the Messages API reference for required fields and Anthropic’s Opus 5.5 migration guide for model-specific changes. Run the minimal request once to verify the current connection and model route; if it fails, use the returned error body to work through the checks. Before routing claude-opus-5-5 through BetterToken, verify on the day of publishing or deployment that the exact model ID is in the current catalog.

1. Confirm the API key, Base URL, and model ID first

A first request needs only three values: your own BetterToken API key, the Anthropic-compatible Base URL, and a currently available model ID.

1. Sign in to BetterToken Workspace and create an API key in your own account. Keep it in a secret manager or local environment file; never commit it to Git or paste it into a support message.
2. Open the current model and pricing catalog and confirm that the exact ID claude-opus-5-5 is available. Anthropic defines it as a fixed model ID without a date suffix, but BetterToken availability and pricing are dynamic.
3. Store the key in an environment variable rather than hard-coding it into the application.

You need your own BetterToken account to create an API key. Create a BetterToken account

For the account-side steps, see the BetterToken quickstart.

2. Keep /v1 out of the Base URL but in the raw request path

Use https://bettertoken.ai as the Anthropic SDK Base URL; use https://www.bettertoken.ai/v1/messages for a direct HTTP Messages request.

https://bettertoken.ai

Do not use /messages as the Base URL, and do not append /v1/messages twice when an SDK already adds the resource path. Set the three values in the current 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"

Run the first line by itself. The terminal then waits for hidden input: type or paste the API key and press Enter; no characters are echoed. The key is exported only in the current shell, while history records the read command rather than the secret. Do not append the key to the command line.

claude-opus-5-5 is the model ID Anthropic documents for Claude Platform. If the current BetterToken catalog does not show that exact ID, stop and verify availability instead of guessing an alias.

3. Send the smallest useful request

Leave out tools, tool_choice, and thinking on the first test so that advanced options cannot hide a basic connection problem.

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\": \"Reply with exactly: pong\"}
    ]
  }"

This request uses the exact model ID, includes a positive max_tokens, omits thinking, and does not force a tool call. The example sets max_tokens to 4096, the value used in Anthropic’s migration example, so adaptive thinking and the short reply share a less restrictive budget. Treat it as a diagnostic starting point, not a tested guarantee or production recommendation; size production requests for the expected answer, effort, cost, and latency.

--fail-with-body keeps the response body when the server returns a 4xx or 5xx status. Redact the API key, complete prompts, model output, and other sensitive fields before sharing logs.

4. Verify success without assuming content[0] is text

HTTP 200 with a top-level type of message means the endpoint accepted and processed the request. For this short-answer check, a text block confirms that content generation completed; adaptive thinking and response text share max_tokens, so a valid response can exhaust the limit before text appears.

Check these signals:

• the top-level type is message;
• the top-level model matches the requested model;
• stop_reason is end_turn and the content array contains at least one block whose type is text when the short-answer check completes normally;
• if stop_reason is max_tokens, the response is valid but truncated: raise max_tokens and retry, or lower an explicitly high effort level when deep reasoning is unnecessary;
• if no text block appears and stop_reason is not max_tokens, preserve the full response and diagnose that stop reason before changing the key or Base URL; missing text alone is not a connectivity failure;
• your parser selects blocks by type instead of reading content[0].text unconditionally;
• usage contains input and output token counts;
• BetterToken Dashboard shows the request at the expected time, with its model, status, input/output/cache tokens, and charge.

The official Anthropic Messages API reference documents the response shape, and Anthropic’s stop-reason guide explains how to handle truncation. The Dashboard is useful for reconciling the request and usage record; it should not be described as guaranteed storage for the full prompt or response.

5. Check general Messages errors and Opus 5.5 changes

The request still uses an older model name

Replace an older ID or a guessed dated alias with claude-opus-5-5. Anthropic’s migration guide defines this as a fixed ID with no date suffix. Cloud platforms can use platform-specific identifiers; this BetterToken Anthropic-compatible example should use the exact ID shown in the current BetterToken catalog.

max_tokens is missing

Include a positive max_tokens in every Messages request. A missing field is a general Messages API validation error, not an Opus 5.5 migration change. It is a hard cap on total output, including thinking and final text. Even a smoke test needs enough room for both; if stop_reason is max_tokens, raise the cap and retry instead of treating the call as a connection failure.

The payload disables thinking or sets a manual budget

The simplest fix is to remove the entire thinking field. Opus 5.5 always uses adaptive thinking. Anthropic’s migration guide identifies both of these old forms as rejected with a 400 response:

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

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

When an explicit field is useful, use {"thinking": {"type": "adaptive"}}. Control reasoning depth with output_config.effort; supported levels are low, medium, high, xhigh, and max, with medium as the default. The minimal connectivity request does not need either field.

The payload forces tool_choice

Use only {"type": "auto"} or {"type": "none"} for tool_choice. Opus 5.5 rejects {"type": "any"} and {"type": "tool", "name": "..."}. For a tool workflow, let the model choose under auto, state in the prompt when the tool should be used, and validate each schema before enabling strict tool use.

6. For other status codes, read the body before changing the request

Status	Check first	Avoid
400	Valid JSON; model, max_tokens, messages, thinking settings, and tool_choice	Replacing the key or retrying the same invalid payload repeatedly
401 / 403	Complete key, correct account or key group, correct Base URL	Sending the full key to support
404	A raw HTTP call must use /v1/messages	Treating /messages as the complete route
429	Retry guidance in the response, balance, limits, and request history	Retrying in a tight loop

Clear stale variables from another provider before configuring the shell again:

unset ANTHROPIC_API_KEY
unset ANTHROPIC_BASE_URL
unset CLAUDE_MODEL_ID

After a fix, repeat the same minimal request. Changing the model, endpoint, prompt, and advanced parameters at the same time makes it much harder to identify what actually solved the problem.

7. Separate Anthropic list pricing from BetterToken’s current price

Anthropic’s September 22, 2026 launch page listed Claude Platform pricing at $4 per million input tokens, $20 per million output tokens, $0.20 for cache reads, and $5 for cache writes. Those figures are Anthropic’s publicly listed launch-time platform prices. BetterToken pricing is dynamic, so check the current pricing page and verify one small request against your own Dashboard record.

Thinking tokens are billed as output tokens, and max_tokens covers thinking plus final text. A workload migrated from a configuration that disabled thinking can therefore have a different output-token profile even when the prompt stays the same. Before production use, check the current BetterToken pricing page and reconcile a small request against the Dashboard record.

Before moving on to an SDK, streaming, or production traffic, confirm the model ID again, keep the key out of source control, size max_tokens for the task, parse content by block type, avoid forced tool choice, and preserve a redacted error body for diagnostics. Continue with the BetterToken API Reference and Anthropic’s Opus 5.5 migration guide.