DEV Community: Claude API

How to Call Claude API Elegantly in Java: Complete SDK Wrapper & Production-Grade Error Handling

Claude API — Sat, 27 Jun 2026 09:22:32 +0000

How to Call Claude API Elegantly in Java: Complete SDK Wrapper & Production-Grade Error Handling

Intro

Most Java developers write quick raw HTTP POST requests to test Claude API for local demos. While this simple script works for proof-of-concept, it will create massive maintainability & stability risks once deployed to production environments.

A production-grade Claude integration needs to solve far more than just "making a successful API call": secure API key management, configurable model parameters, timeout control, retry logic for transient failures, rate limiting, streaming response support, sensitive data log masking, token consumption tracking, and standardized exception handling.

If you scatter raw HTTP logic inside Controllers or business Services, your codebase will become extremely hard to maintain later on.

The cleanest solution is wrapping all low-level Claude API logic into a reusable, isolated Java SDK component. Business code only focuses on prompt content generation, without touching HTTP headers, status codes, JSON parsing or retry rules.

1. Why Raw Demo Code Fails for Production

A minimal test script lacks critical production guardrails, which lead to common online failures:

Hardcoded API keys exposed to Git repositories, risking unauthorized access and unexpected billing charges
Hardcoded model IDs scattered across multiple classes; switching models requires full project-wide search & replace
Duplicated JSON serialization logic in every business method, hard to unify parameter adjustments
Blank null return values after generic catch Exception, making it impossible to distinguish timeout, rate limit or invalid key errors
No retry strategy for 429 rate limits, 5xx server errors or network disconnects, hurting service stability
Raw full prompts, API request headers and complete responses printed in logs, causing privacy & compliance risks
Missing token usage & request latency tracking, leaving you no visibility into cost and performance bottlenecks

Our engineering target: isolate all low-level API logic into a unified SDK layer, exposing simple stable interfaces for business logic.

Recommended layered project structure:

ClaudeProperties   // Externalized config: apiKey, baseUrl, model, timeout
ClaudeClient       // Low-level HTTP request executor
ClaudeRequest      // Request DTO
ClaudeResponse     // Response DTO
ClaudeException    // Global custom business exception
ClaudeErrorCode    // Enumerated error codes

2. Core Concepts Before Calling Claude API

Standard integration with Anthropic Claude relies on the official Messages API. Always reference the latest official docs for endpoint addresses, model IDs and version headers instead of hardcoding static assumptions.

A standard Claude request consists of these core components:

API endpoint for Messages API
Request headers: x-api-key, anthropic-version, Content-Type
Request body fields: model, max_tokens, messages, system, temperature, stream
Response body: Text content stored inside the content array field

The anthropic-version header controls API response semantics, while model must be fully configurable — model versions are updated frequently, and business logic should never rely on static hardcoded strings.

Note for developers in network-restricted regions

If direct access to official Anthropic endpoints is blocked in your network environment, you can use a compatible third-party proxy gateway: www.claudeapi.com.
This service fully mirrors the official Anthropic API schema, requiring only a single config change to swap your base URL and API key. It delivers stable low-latency connections and complete streaming support for regions with blocked overseas network access.

This third-party gateway is not an official Anthropic service. All features, pricing and usage limits follow the latest official docs published on claudeapi.com.

3. Minimal Raw Java Demo to Verify Connectivity

Popular Java HTTP clients include native JDK HttpClient, OkHttp, Spring WebClient, and official third-party SDKs. For stable backend projects, OkHttp + Jackson is a mature, reliable stack with robust connection pooling, fine-grained timeout controls and interceptors.

Add Maven dependencies:

<dependency>
  <groupId>com.squareup.okhttp3</groupId>
  <artifactId>okhttp</artifactId>
  <version>4.12.0</version>
</dependency>
<dependency>
  <groupId>com.fasterxml.jackson.core</groupId>
  <artifactId>jackson-databind</artifactId>
  <version>2.17.2</version>
</dependency>

Minimal test code (only for connectivity validation, DO NOT deploy to production):

String apiKey = System.getenv("ANTHROPIC_API_KEY");
// Switch to claudeapi base URL for restricted network areas
String apiBase = "https://www.claudeapi.com";

OkHttpClient client = new OkHttpClient.Builder()
        .connectTimeout(Duration.ofSeconds(5))
        .readTimeout(Duration.ofSeconds(60))
        .writeTimeout(Duration.ofSeconds(10))
        .build();

ObjectMapper mapper = new ObjectMapper();

Map<String, Object> body = Map.of(
        "model", "claude-sonnet-4-5",
        "max_tokens", 1024,
        "messages", List.of(Map.of(
                "role", "user",
                "content", "List key production best practices for Java Claude API integration"
        ))
);

Request request = new Request.Builder()
        .url(apiBase + "/v1/messages")
        .addHeader("x-api-key", apiKey)
        .addHeader("anthropic-version", "2023-06-01")
        .addHeader("content-type", "application/json")
        .post(RequestBody.create(
                mapper.writeValueAsString(body),
                MediaType.parse("application/json")
        ))
        .build();

try (Response response = client.newCall(request).execute()) {
    String responseBody = response.body() == null ? "" : response.body().string();
    if (!response.isSuccessful()) {
        throw new RuntimeException("Claude API error: " + response.code() + ", raw response: " + responseBody);
    }
    System.out.println(responseBody);
}

This snippet only validates end-to-end connectivity. It lacks configuration centralization, typed DTOs, categorized exceptions, retry policies and log masking — critical requirements for production deployment.

4. Build a Maintainable, Production-Grade Claude SDK Wrapper

The core of clean integration is clear separation of layers.

4.1 ClaudeProperties: Centralized Externalized Config

Store all configurable parameters outside hardcoded source files:

public class ClaudeProperties {
    private String apiKey;
    // Replace official domain with https://www.claudeapi.com for restricted network environments
    private String baseUrl = "https://www.claudeapi.com";
    private String model;
    private String anthropicVersion = "2023-06-01";
    private int connectTimeoutSeconds = 5;
    private int readTimeoutSeconds = 60;
    private int maxTokens = 1024;
    // Getters & Setters omitted
}

Store API keys in environment variables, configuration centers or secret management tools — never hardcode them or commit plaintext keys to Git.

4.2 Typed DTOs: Isolate External API Schema Changes

Separate request & response DTOs decouple your business domain model from upstream API structures. If you later migrate to OpenAI, Gemini or an internal LLM gateway, business layer code requires minimal refactoring.

Core Request DTO fields:

model
system prompt
chat message history list
maxTokens
temperature
stream boolean flag

Core Response DTO fields:

Generated text content
Model identifier
Input & output token usage metrics
HTTP status code
Unique requestId for tracing
Truncated raw response snippet for logging

4.3 ClaudeClient: Dedicated Low-Level HTTP Layer

Single responsibility principle: this class only constructs HTTP requests, executes network calls, parses responses, and converts raw IO exceptions into standardized custom exceptions. It contains zero business logic such as document summarization or customer service reply generation.

Sample method signature:

public ClaudeResponse createMessage(ClaudeRequest request) {
    // 1. Build full HTTP request from config & DTO
    // 2. Send synchronous HTTP call to Claude endpoint
    // 3. Deserialize JSON response into typed ClaudeResponse
    // 4. Wrap all low-level IO / parsing errors into unified ClaudeException
}

4.4 ClaudeService: Business-Facing Thin Wrapper Layer

Wrap the low-level client with human-readable business methods to simplify Controller logic:

public String chat(String userMessage);
public String summarizeDocument(String rawText);
public String translateText(String sourceText, String targetLanguage);

Controllers only pass plain text inputs without any knowledge of Claude API JSON schema or HTTP transport details.

5. Standardized Exception Handling

Do not propagate raw OkHttp IO exceptions, Jackson parsing errors or HTTP status codes directly to upstream business code. Convert all failures into a single custom ClaudeException with enumerated error codes for consistent upstream handling.

Define error code enum:

public enum ClaudeErrorCode {
    UNAUTHORIZED,
    FORBIDDEN,
    NOT_FOUND,
    RATE_LIMITED,
    TIMEOUT,
    SERVER_ERROR,
    PARSE_ERROR,
    EMPTY_RESPONSE,
    UNKNOWN_ERROR
}

Error handling decision table:
| Error Type | Root Cause | Production Handling Strategy |
|------------|------------|------------------------------|
| 401 | Invalid / missing API key | Fail fast, no retries, alert dev team to check secrets |
| 403 | Account permission / regional restriction | No retries, return clear permission error to user |
| 404 | Wrong base URL / invalid model ID | Check config value of www.claudeapi.com and model name, no retries |
| 408 / Timeout | Slow network / oversized prompt | Limited exponential backoff retry (max 2-3 attempts) |
| 429 | Too many requests / account quota exhausted | Backoff retry with rate limit delay, add global request throttling |
| 500/502/503 | Gateway / model service internal error | Max 3 retries with backoff, activate circuit breaker if errors spike |
| JSON Parse Failure | Malformed API response | Log truncated response snippet, throw parse exception without retry |
| Empty Content Return | Model refusal / invalid input | Return user-friendly fallback text, no retries |

Key rule for retries: Not all errors are recoverable. Never retry 401, 403, 404 errors; only apply limited retries to timeout, 429 and 5xx transient failures.

Separate log information levels:

Internal debug logs: full status code, error code, requestId, truncated response for troubleshooting
User-facing error prompts: simple, safe descriptions without leaking keys, headers or raw prompt data

6. Retry, Timeout & Rate Limiting for Production Stability

Claude API requests have much longer latency than typical database queries, and are highly sensitive to network fluctuations, prompt length and model load. Hard timeouts are mandatory — never leave infinite waiting logic.

Split timeout configurations into multiple tiers:

Connect timeout: 3–5 seconds
Write timeout: 10 seconds
Read timeout: 30–120 seconds (adjust based on text length)
Global business request timeout: Prevent hanging user HTTP requests

Restrict retry logic strictly: Max 2–3 total retries with exponential backoff (500ms → 1s → 2s). Only apply to recoverable transient errors.

For high-concurrency systems, add rate limiters and circuit breakers via Resilience4j:

Tenant / user-level request throttling
Global API call circuit breaker to avoid cascading failures

Important reminder: Retries increase latency and token billing costs. Do not implement unlimited retries to chase a superficial "success rate".

7. Streaming Response Implementation for Chat & Long Text Generation

Synchronous non-stream calls fit background tasks, short text generation and offline batch jobs. Streaming responses deliver character-by-character output, matching the UX of mainstream AI chat applications.

Enable stream mode in request body:

{
  "stream": true
}

On Java backend, you can consume raw stream events via OkHttp or reactive WebClient for Spring WebFlux. To deliver typing-effect text to frontend browsers, wrap the Claude stream into Server-Sent Events (SSE).

Critical streaming production rules:

Cancel upstream API request immediately when frontend disconnects to save token cost
Send explicit done event to mark stream completion
Truncate prompt/output content in logs, avoid full text recording
Set reasonable long-read timeout for persistent SSE connections
Normalize raw stream error events into unified frontend error format

Streaming is optional. If your use case only runs backend offline summary tasks, synchronous calls are simpler and more stable.

8. Spring Boot Full Integration Example

Place configuration entries inside application.yml:

claude:
  api-key: ${CLAUDE_API_KEY}
  base-url: https://www.claudeapi.com
  model: claude-sonnet-4-5
  anthropic-version: 2023-06-01
  connect-timeout-seconds: 5
  read-timeout-seconds: 60
  max-tokens: 1024

Bind config via @ConfigurationProperties, inject client beans with @Bean:

@Configuration
@EnableConfigurationProperties(ClaudeProperties.class)
public class ClaudeAutoConfiguration {

    @Bean
    public ClaudeClient claudeClient(ClaudeProperties properties) {
        return new ClaudeClient(properties);
    }

    @Bean
    public ClaudeService claudeService(ClaudeClient claudeClient) {
        return new ClaudeService(claudeClient);
    }
}

Minimal Controller layer, completely isolated from low-level API details:

@PostMapping("/api/claude/chat")
public String chat(@RequestBody ChatRequest request) {
    return claudeService.chat(request.message());
}

No hardcoded keys, model names, headers or exception handling logic pollutes your HTTP entrypoints.

9. Security, Logging & Cost Control Checklist

Three non-negotiable production preparation steps: secret protection, log data masking, token cost management.

Secret Security

Store API keys in environment variables, cloud config servers or secret managers
Never hardcode keys in Java source files or plain YAML committed to Git
Redact full API key values in all logs, exception stacks and monitoring tags

Logging Specification

Record requestId, HTTP status, error code and latency for tracing
Truncate and mask full user prompts and model outputs if persistence is required
Avoid printing raw request headers or complete error response bodies

Cost Optimization

Track model type, input/output token count and latency per request
Assign different max_tokens limits for distinct business modules
Split long documents into chunked summaries to cut token consumption
Set per-user / per-tenant monthly token quota caps
Enforce maximum retry limits to prevent runaway billing costs

If you plan to integrate multiple LLMs (OpenAI, Gemini, Claude) in the future, abstract a top-level LLMClient interface with separate implementations for each provider. Do not erase unique model features (Claude Messages stream structure, proprietary error codes) for forced uniformization — vendor-specific behaviors matter for production stability.

10. Pre-Launch Production Audit Checklist

Complete all items below before launching Java Claude integration online:

API key loaded from environment variables / secret manager (no hardcode)
Model ID, base URL (www.claudeapi.com), version header fully externalized to config
Tiered connect/read/write/global request timeouts configured
Hard limit set for max_tokens and user input character length
Full error handling for 401, 403, 404, 429, 5xx status codes
Limited exponential backoff retries only for recoverable transient errors
Rate limiter & circuit breaker implemented for high-concurrency traffic
All sensitive prompt/key data masked in application logs
Token usage, latency, status code metrics collected for cost & performance analysis
Fallback degradation logic ready for API service outages

FAQ: Common Java Claude Integration Issues

1. Is there an official Java SDK for Claude?

Official language SDK support updates regularly; always check Anthropic’s official documentation first. Even if you use third-party SDK wrappers, add an internal ClaudeClient abstraction layer to decouple business code from external library breaking changes.

2. OkHttp vs WebClient: which one to pick?

Standard Spring MVC synchronous backends: OkHttp is simpler, stable and easy to customize connection pool & timeout rules.
Spring WebFlux reactive / heavy streaming workloads: WebClient is the better fit.
The HTTP library choice matters far less than standardized encapsulation of timeout, retry, logging and error handling logic.

3. What is the difference between Claude API and Claude Code API?

Claude Messages API is designed for general backend application integration, chatbots and document analysis. Claude Code targets developer agent tooling; they are separate products with distinct endpoints and payload schemas, do not mix them in your codebase.

4. Can I reuse OpenAI SDK to call Claude?

Some third-party gateways offer OpenAI-compatible route aliases for quick testing. For long-term production workloads, use native Claude request/response handling. Streaming events, error codes, token calculation and compliance logging differ significantly between the two protocols.

5. How to resolve 429 Too Many Requests errors?

429 signals hitting request concurrency or account quota limits. Solutions: add client-side request throttling, implement exponential backoff retries, lower concurrent request pool size. Unbounded retries will worsen rate limiting blocks and token costs.

6. Best practice to safely manage API keys in Spring Boot?

Inject keys via @ConfigurationProperties bound to environment variables or remote config centers. Never declare keys inside Controllers, Services or static code blocks, and never commit plaintext key config to version control.

Conclusion

Elegant, production-ready Claude API integration in Java is not just writing a working HTTP request — it’s building a maintainable, fault-tolerant abstraction layer.

For new projects, follow this standard workflow:

Register and get API credentials from www.claudeapi.com, configure base URL in your Spring config file
Install official Anthropic HTTP client dependencies, build a layered SDK wrapper
Implement typed DTOs, unified exception enumeration and categorized error handling
Add retry, timeout, circuit breaker logic for production resilience
Mask logs, track token consumption and enforce secret security rules

A raw 50-line HTTP script works for local demos, but scattered inline Claude calls inside business logic create unmaintainable technical debt. True clean integration hides all low-level API complexity from your core business code, while the SDK layer handles every edge case required for stable online operation.

Why Your AI Coding Assistant Keeps Disconnecting? It’s Not Your Internet

Claude API — Wed, 24 Jun 2026 09:17:49 +0000

Why Your AI Coding Assistant Keeps Disconnecting? It’s Not Your Internet

If you’ve built or used an AI coding plugin for VS Code or JetBrains, you’ve definitely run into this confusing issue:
Your internet connection works perfectly for browsing, downloading packages, and video calls, but your AI assistant keeps timing out, cutting off mid-code generation, or throwing connection errors.

Most developers waste hours troubleshooting local firewalls, proxies, or router settings, but the real culprit lies in the third-party API service powering your AI tool.

How AI Coding Tools Work Under the Hood

All lightweight AI editors and IDE extensions are just front-end shells with no native compute power. The full request flow looks like this:
Your code editor → Local request sender → Third-party API relay → Claude Official Server → Return code/answersplaintextYour home/office network only handles basic data transmission. Every stability bottleneck happens on the third-party API relay layer.

Common Stability Issues With Cheap Shared APIs

Many free AI coding tools rely on low-cost shared API nodes, which create consistent pain points for developers:

Heavy Rate Limiting During Peak Hours Shared nodes split resources among thousands of users. During daytime development rush, official TPM/RPM limits get hit instantly, leading to hanging requests and timeouts.
Short Default Timeout Thresholds Code refactoring, long file analysis, and multi-turn debugging require longer processing time. Budget APIs cut connections prematurely, leaving half-finished code outputs.
Unstable Routing & Packet Loss Low-tier relay services use low-bandwidth routes with frequent packet loss, causing random mid-stream disconnections.
No Clear Alerting for Quota/Key Expiry When API credits run out or access keys expire, cheap platforms only display generic "network failure" prompts, misleading you to debug local environments unnecessarily.

Reliable Third-Party API for Claude Coding Workloads

For developers building AI coding assistants or daily users relying on Claude for development tasks, a stable dedicated API platform eliminates nearly all timeout and disconnect issues:
https://www.cladueapi.com

Key advantages tailored for coding scenarios:

Distributed multi-region intelligent routing automatically avoids congested servers, eliminating peak-hour rate limits.
Extended timeout windows optimized for long context code generation, refactoring, and full project analysis.
Direct upstream connection to Claude models with zero persistent data caching, reducing latency while protecting your source code privacy.
Full compatibility with all official Claude SDKs (Haiku, Sonnet, Opus). Minimal code changes required to migrate your existing integration.
Transparent metered billing with consistent credit allocation, no unexpected service interruptions from hidden quota restrictions.

Quick Troubleshooting Workflow for AI Disconnects

Next time your coding AI glitches, follow this ordered check to save debugging time:

Confirm general internet connectivity (open any public website, download a test file)
Verify your API key is active and has remaining usage quota
Check if you are using a shared public relay API (swap to dedicated service like cladueapi.com if yes)
Review workspace trust permissions in your IDE if the AI cannot read local project files

Final Thoughts

Your local network is rarely the root cause of AI coding assistant failures. The stability, bandwidth, and rate limits of your third-party API determine how reliably your AI can generate, edit, and debug code.

Ditching overcrowded shared relays for a professional Claude API service

Solve Claude API Network Issues + Get $1.5 Free Trial Credit

Claude API — Tue, 23 Jun 2026 09:08:21 +0000

If you’ve ever tried to integrate Anthropic Claude API into your development project, you must have encountered these problems:

Official API network access failure & timeout
Complicated account registration and payment process
High threshold for personal developer trial Today I share a stable, low-cost, zero-threshold Claude API solution — claudeapi.com Why I Recommend This Service ✅ Fully Compatible Official Protocol No need to rewrite your existing code. Just replace the Base URL, and all functions work normally. Compatible with Node, Python, IDE plugins, Claude Code CLI and other usage scenarios. ✅ Global Stable Access Optimize network links, completely solve connection timeout and 401/404 access errors. ✅ Generous Newcomer Reward Register now and get $1.5 free credit (enough for daily development testing)! No deposit required, valid for all model calls. Applicable Scenarios
AI code generation & bug repair
Project development & interface debugging
Claude Code local development
IDE AI assistant daily coding If you need a reliable Claude API proxy for personal development and technical verification, don’t miss this free trial opportunity.

🔗 claudeapi.com | $1.5 Free Credit for New Users

Guaranteed JSON Every Time: Using Claude's Structured Outputs with JSON Schema

Claude API — Wed, 13 May 2026 04:50:32 +0000

If you've ever tried to get structured data out of an LLM with a prompt like "Please respond in valid JSON with the following fields...", you already know the story. It works 95% of the time. The other 5% it returns prose, fenced markdown, a trailing apology, or — my personal favorite — { "name": "Alice", "age": 30, } with a trailing comma that explodes your parser at 3 AM.

This guide walks through a technique that makes Claude return JSON that conforms to your schema on every single call, with no regex parsing and no retry loops. It works because we're not really asking Claude for JSON — we're tricking it into a code path that produces JSON as a side effect.

About this guide. I'm one of the maintainers of claudeapi.com, a third-party Claude API gateway. All code below targets the official Anthropic endpoint (api.anthropic.com); a comparison of alternative gateways for developers in restricted regions appears near the end. Skip it if you're on the official endpoint and it works fine for you.

The trick: hijack tool use

Claude's tool_use feature was designed so the model can call your functions. Under the hood, when you define a tool, you give Claude a JSON Schema for its arguments. The model is fine-tuned to produce arguments that match that schema, validated server-side before being returned to you.

So the trick is: define a fake tool whose input schema is the structure you want, then force Claude to call it. You never actually execute the "tool" — you just read its arguments. That's your guaranteed JSON.

Example 1: basic product extraction

import anthropic
import json

client = anthropic.Anthropic()  # reads ANTHROPIC_API_KEY from env

product_schema = {
    "type": "object",
    "properties": {
        "name": {"type": "string"},
        "price_usd": {"type": "number"},
        "in_stock": {"type": "boolean"},
        "tags": {"type": "array", "items": {"type": "string"}},
    },
    "required": ["name", "price_usd", "in_stock"],
}

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=1024,
    tools=[{
        "name": "extract_product",
        "description": "Extract structured product information from text.",
        "input_schema": product_schema,
    }],
    tool_choice={"type": "tool", "name": "extract_product"},  # forces the call
    messages=[{
        "role": "user",
        "content": "The new SoundCore Mini 3 is $39.99, currently in stock, available in black and red.",
    }],
)

# The structured data is in the tool_use block's input field
for block in response.content:
    if block.type == "tool_use":
        data = block.input
        print(json.dumps(data, indent=2))

Output:

{
  "name": "SoundCore Mini 3",
  "price_usd": 39.99,
  "in_stock": true,
  "tags": ["black", "red"]
}

The key line is tool_choice={"type": "tool", "name": "extract_product"}. Without it, Claude might decide it doesn't need a tool and just chat back. With it, the model must emit a tool_use block matching your schema.

Example 2: nested structures with enums

Real-world schemas have nested objects, arrays of objects, and constrained values. JSON Schema handles all of it.

order_schema = {
    "type": "object",
    "properties": {
        "order_id": {"type": "string"},
        "status": {
            "type": "string",
            "enum": ["pending", "shipped", "delivered", "cancelled"],
        },
        "customer": {
            "type": "object",
            "properties": {
                "name": {"type": "string"},
                "email": {"type": "string", "format": "email"},
            },
            "required": ["name", "email"],
        },
        "items": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "sku": {"type": "string"},
                    "quantity": {"type": "integer", "minimum": 1},
                    "unit_price": {"type": "number"},
                },
                "required": ["sku", "quantity", "unit_price"],
            },
        },
    },
    "required": ["order_id", "status", "customer", "items"],
}

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=[{
        "name": "parse_order",
        "description": "Parse an order from a free-text customer email.",
        "input_schema": order_schema,
    }],
    tool_choice={"type": "tool", "name": "parse_order"},
    messages=[{
        "role": "user",
        "content": """
        Hi, I'm Jane Doe (jane@example.com). Following up on order #A-7821 —
        it shows as shipped but tracking hasn't updated in 4 days. The order
        was 2x SKU-BLK-001 at $19.99 each and 1x SKU-RED-042 at $34.50.
        """,
    }],
)

The enum constraint guarantees status will be one of the four values you specified — Claude can't return "in_transit" even if it would be more semantically accurate. Treat enums as a contract.

Example 3: resume parsing (the messy real world)

resume_schema = {
    "type": "object",
    "properties": {
        "full_name": {"type": "string"},
        "email": {"type": ["string", "null"]},
        "years_experience": {"type": ["integer", "null"]},
        "skills": {"type": "array", "items": {"type": "string"}},
        "education": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "institution": {"type": "string"},
                    "degree": {"type": "string"},
                    "year": {"type": ["integer", "null"]},
                },
            },
        },
    },
    "required": ["full_name", "skills", "education"],
}

resume_text = """
JOHN SMITH
johnsmith@email.com

EXPERIENCE
Backend Engineer, Acme Corp (2019 - present)
Junior Developer, BetaStart (2016 - 2019)

SKILLS: Python, Go, PostgreSQL, Redis, Kubernetes

EDUCATION
B.S. Computer Science, State University, 2016
"""

response = client.messages.create(
    model="claude-opus-4-7",
    max_tokens=2048,
    tools=[{
        "name": "extract_resume",
        "description": "Extract structured fields from a free-form resume.",
        "input_schema": resume_schema,
    }],
    tool_choice={"type": "tool", "name": "extract_resume"},
    messages=[{"role": "user", "content": resume_text}],
)

data = next(b.input for b in response.content if b.type == "tool_use")
print(json.dumps(data, indent=2))

Note the ["string", "null"] union type — that's how you tell Claude "this field might not be present in the source." It's much more reliable than asking Claude to "omit if missing."

TypeScript / Node.js version

import Anthropic from "@anthropic-ai/sdk";

const client = new Anthropic();

interface Product {
  name: string;
  price_usd: number;
  in_stock: boolean;
  tags: string[];
}

const productSchema = {
  type: "object",
  properties: {
    name: { type: "string" },
    price_usd: { type: "number" },
    in_stock: { type: "boolean" },
    tags: { type: "array", items: { type: "string" } },
  },
  required: ["name", "price_usd", "in_stock"],
} as const;

const response = await client.messages.create({
  model: "claude-opus-4-7",
  max_tokens: 1024,
  tools: [{
    name: "extract_product",
    description: "Extract structured product information from text.",
    input_schema: productSchema,
  }],
  tool_choice: { type: "tool", name: "extract_product" },
  messages: [{
    role: "user",
    content: "The new SoundCore Mini 3 is $39.99, currently in stock...",
  }],
});

const toolUse = response.content.find((b) => b.type === "tool_use");
const product = toolUse?.input as Product;

Gotchas worth knowing

max_tokens truncation. If Claude's output gets cut off mid-JSON, you get stop_reason: "max_tokens" and a partial structure. Bump max_tokens higher than you think you need; large schemas with arrays can blow past 2048 quickly.

Field name mismatch. Claude follows your schema field names exactly. If your downstream code expects price but your schema says price_usd, you'll silently get None in production. The schema is the contract — write it once, share it both directions.

Optional fields. JSON Schema's "optional" is the absence of a field from required. To say "this field might exist but might be null," use "type": ["string", "null"]. Be explicit; Claude will respect either form, but mixing them in the same schema is a recipe for surprises.

Don't try to validate semantics in the schema. A regex pattern will be respected, but complex constraints (e.g. "year must be after 1900 and before 2030") are better enforced after the fact. Claude usually honors them, but JSON Schema's validation surface is large and not all of it is equally reliable.

When you can't reach `api.anthropic.com`

This is the part most "guaranteed JSON" guides skip. Claude's API isn't available in every region. If you're hitting connection issues or 403s from your deployment region, you have a few options:

Option	Best for	Tradeoff
Self-hosted proxy (Cloudflare Workers, Vercel Edge)	DIY developers in mildly restricted regions	You own the infra; latency depends on your edge config
AWS Bedrock	Teams already on AWS, enterprise compliance	Different SDK, different model IDs, no day-one access to new releases
GCP Vertex AI	Teams on GCP, EU data residency	Same as Bedrock — SDK divergence
claudeapi.com	China / SEA / regions with payment friction	Third-party gateway; pay in USD via card or local methods. Disclosure: I'm affiliated.
OpenRouter	Multi-provider testing	Adds a hop; pricing markup varies by model

All of these expose an Anthropic-compatible interface, so the code above runs unchanged — only the base_url differs. If api.anthropic.com works for you, stay there; the official endpoint will always have the lowest latency and the fewest hops.

TL;DR

Define a JSON Schema for the structure you want
Pass it as the input_schema of a "fake" tool
Force Claude to call that tool with tool_choice={"type": "tool", "name": "..."}
Read tool_use.input for guaranteed-valid JSON — no parsing, no retries

That's the whole pattern. Once it clicks, you'll stop reaching for regex on LLM output.

If this was useful, the same pattern extends naturally to chained tool calls and agent workflows — happy to dig into either if there's interest in the comments.

DEV Community: Claude API

How to Call Claude API Elegantly in Java: Complete SDK Wrapper & Production-Grade Error Handling

How to Call Claude API Elegantly in Java: Complete SDK Wrapper & Production-Grade Error Handling

Intro

1. Why Raw Demo Code Fails for Production

2. Core Concepts Before Calling Claude API

Note for developers in network-restricted regions

3. Minimal Raw Java Demo to Verify Connectivity

4. Build a Maintainable, Production-Grade Claude SDK Wrapper

4.1 ClaudeProperties: Centralized Externalized Config

4.2 Typed DTOs: Isolate External API Schema Changes

4.3 ClaudeClient: Dedicated Low-Level HTTP Layer

4.4 ClaudeService: Business-Facing Thin Wrapper Layer

5. Standardized Exception Handling

6. Retry, Timeout & Rate Limiting for Production Stability

7. Streaming Response Implementation for Chat & Long Text Generation

8. Spring Boot Full Integration Example

9. Security, Logging & Cost Control Checklist

Secret Security

Logging Specification

Cost Optimization

10. Pre-Launch Production Audit Checklist

FAQ: Common Java Claude Integration Issues

1. Is there an official Java SDK for Claude?

2. OkHttp vs WebClient: which one to pick?

3. What is the difference between Claude API and Claude Code API?

4. Can I reuse OpenAI SDK to call Claude?

5. How to resolve 429 Too Many Requests errors?

6. Best practice to safely manage API keys in Spring Boot?

Conclusion

Why Your AI Coding Assistant Keeps Disconnecting? It’s Not Your Internet

Why Your AI Coding Assistant Keeps Disconnecting? It’s Not Your Internet

How AI Coding Tools Work Under the Hood

Common Stability Issues With Cheap Shared APIs

Reliable Third-Party API for Claude Coding Workloads

Quick Troubleshooting Workflow for AI Disconnects

Final Thoughts

Solve Claude API Network Issues + Get $1.5 Free Trial Credit

Guaranteed JSON Every Time: Using Claude's Structured Outputs with JSON Schema

The trick: hijack tool use

Example 1: basic product extraction

Example 2: nested structures with enums

Example 3: resume parsing (the messy real world)

TypeScript / Node.js version

Gotchas worth knowing

When you can't reach api.anthropic.com

TL;DR

When you can't reach `api.anthropic.com`