2.3 — Claude API Mechanics

CCDV-F Domain 2 · Task 2.3

What You Need to Know

The Messages API is how an application talks to Claude. A request needs exactly three parameters: model, max_tokens, messages. Everything else is optional. The API is stateless: the application resends the transcript every turn.

Response Fields

• content — list of typed blocks: text, tool_use, thinking
• stop_reason — why generation ended: end_turn, max_tokens, stop_sequence, tool_use, pause_turn, refusal, model_context_window_exceeded
• usage — token counts; total input = input_tokens + cache_creation_input_tokens + cache_read_input_tokens

Read stop_reason before the content.

Tools at the Wire Level

Tool definition: name, description, JSON Schema input_schema. Model stops with stop_reason tool_use and emits a tool_use block. Caller executes the tool, continues with a user turn holding a tool_result block whose tool_use_id matches. tool_choice: auto, any, tool, none. Server tools (web search) invert the execution side — Anthropic runs them.

Streaming

stream: true → server-sent events: message_start → content_block_start/delta/stop → message_delta → message_stop. Delta types: text_delta, input_json_delta, thinking_delta. Streaming moves time-to-first-token; it does not change total cost or generation time.

Vision

Images as content blocks: base64, url, or file id from Files API. Supported: JPEG, PNG, GIF, WebP. Cost is patch-based (~1 visual token per 28×28 patch). Pre-resize to control cost and latency.

Thinking

Current models use thinking.type adaptive with depth steered by output_config.effort. Older extended-thinking shape (type enabled + budget_tokens) is deprecated. In multi-turn tool use, pass thinking and redacted_thinking blocks back exactly as received.

Prompt Caching

Prefix hashing. cache_control marker of type ephemeral caches everything up to that point. Hit only if prefix is 100% identical (hierarchy: tools → system → messages). Stable content first, volatile content last. Entries live 5 minutes by default (or 1h with ttl).

Batch Versus Realtime

Message Batches API: 50% discount; up to 100,000 requests or 256 MB; results at completion or 24-hour mark. Latency-tolerant, cost-dominated work → batch. Interactive → realtime.

Vendor Surfaces

Same Messages API shape everywhere. What changes: authentication, endpoint, model-ID format, feature parity, release timing. Bedrock and Google Cloud (Google managed) do not carry Batches API, Files API or most server tools.

Error Surface

Status	Error type
400	invalid_request_error
401	authentication_error
402	billing_error
403	permission_error
404	not_found_error
409	conflict_error
413	request_too_large
429	rate_limit_error
500	api_error
504	timeout_error
529	overloaded_error

SDKs retry transient failures (connection, 429, 5xx) twice by default with exponential backoff. A 529 is overload — back away. Monthly spend cap returns 429 with no retry-after (enforced_spend_limit_reached).

Exam Traps

Focus on exact parameter names, stop_reason values, streaming event order, caching hierarchy, and the distinction between client tools and server tools.