Request & Response Configuration

Relevant source files

The following files were used as context for generating this wiki page:

• internal/requestconfig/requestconfig.go
• internal/requestconfig/requestconfig_test.go
• betamessagebatch.go
• messagebatch.go
• schemautil.go
• bedrock/bedrock_test.go

Introduction

The Request & Response Configuration system within the Anthropic Go SDK provides a robust framework for managing HTTP interactions with Anthropic's API services. It centralizes concerns such as request serialization, header management, retry logic, timeout handling, and response deserialization. This system ensures that all outgoing requests are compliant with Anthropic's API specifications while offering flexibility through functional options and middleware.

At the core of this system is the RequestConfig struct, which encapsulates the state of a single request. It handles the transition from high-level parameter structs to raw HTTP requests and manages the lifecycle of the execution, including exponential backoff retries and error parsing.

Core Architecture

Request Lifecycle and Configuration

The lifecycle of a request begins with the creation of a RequestConfig object. This object is populated with context, HTTP methods, URLs, and body data. It supports multiple serialization formats including JSON, Multipart form data, and URL queries.

The diagram shows the sequence from request initiation through serialization, option application, and the retry loop logic.
Sources: internal/requestconfig/requestconfig.go:81-160, internal/requestconfig/requestconfig.go:281-340

Key Data Structures

Component	Description
RequestConfig	Encapsulates request state: HTTP client, timeout, retries, headers, and body readers.
RequestOption	Interface for functional options that modify RequestConfig before execution.
HTTPDoer	Interface describing an HTTP client or custom implementation capable of executing a request.
bodyWithTimeout	A specialized io.ReadCloser that manages context cancellation for streaming responses.

Sources: internal/requestconfig/requestconfig.go:173-200, internal/requestconfig/requestconfig.go:394-398

Detailed Sections

1. Request Options and Middleware

The SDK uses a functional option pattern (RequestOption) to modify request behavior. These options can set API keys, base URLs, or custom headers. Additionally, a middleware system allows for intercepting requests and responses, which is used internally for platform integrations like AWS Bedrock.

• Pre-Request Options: Applied before the full configuration is initialized (e.g., setting global defaults).
• Execution Middleware: Functions of type func(*http.Request, middlewareNext) (*http.Response, error) that wrap the final HTTPClient.Do call.

Sources: internal/requestconfig/requestconfig.go:202-210, internal/requestconfig/requestconfig.go:445-455, bedrock/bedrock_test.go:121-135

2. Retry Logic and Error Handling

The system implements automatic retries for transient failures. Retries are triggered by specific HTTP status codes (408, 409, 429, 5xx) or connection errors.

This diagram illustrates the retry mechanism handling a rate-limit response via backoff.
Sources: internal/requestconfig/requestconfig.go:212-235, internal/requestconfig/requestconfig.go:271-279

Error Extraction:
When an API error occurs, the system extracts the request-id from response headers and includes it in the apierror.Error struct. This is critical for debugging and support.
Sources: internal/requestconfig/requestconfig_test.go:26-55, internal/requestconfig/requestconfig.go:364-375

3. Serialization and Schema Transformation

For specialized features like "Structured Outputs" or "Tool Use," the SDK must transform standard JSON schemas into a format compatible with Anthropic's strict requirements (e.g., ensuring additionalProperties: false).

func transformSchema(jsonSchema map[string]any) map[string]any {
    // Preserves $ref, handles anyOf/oneOf, enforces additionalProperties: false
    // Filters supported string formats (date-time, email, uuid, etc.)
    // ...
}

Sources: schemautil.go:56-110, schemautil.go:140-160

4. Batch Processing Configuration

The BetaMessageBatchService and MessageBatchService utilize the request configuration system to manage long-running asynchronous operations. These services configure specific anthropic-beta headers and use results_url for final data retrieval.

Parameter	Type	Description
Requests	[]BatchRequest	List of individual message creation requests.
ProcessingStatus	string	current state: in_progress, canceling, or ended.
ResultsURL	string	Location of the .jsonl file containing batch results.

Sources: betamessagebatch.go:167-195, messagebatch.go:136-160

Conclusion

The Request & Response Configuration system provides a standardized, resilient layer for communication with Anthropic. By abstracting the complexities of HTTP retries, header management (including platform-specific versions), and schema transformations, it allows developers to focus on high-level AI interactions while ensuring robust error handling and platform compliance.