Spring Boot で Claude API のエラー・レート制限に強くするThis article explains how to implement robust error handling and rate-limit…

Calling large language model APIs in production introduces failure modes that many web developers rarely encounter with conventional REST services. Requests can be throttled, temporarily overloaded, or interrupted mid-stream, and a naive integration that assumes every call succeeds will surface those problems directly to end users. This article outlines how to build error handling and rate-limit resilience for Claude API calls within a Spring Boot application, a combination that is increasingly common as Java teams add generative features to existing services.

The starting point is understanding what can go wrong. Anthropic's API, like most HTTP services, communicates problems through status codes. A 429 indicates that a rate limit has been exceeded, a 529 signals that the service is temporarily overloaded, and 500-series errors point to transient server issues. By contrast, 400-level errors such as 401 (authentication) or 422 (invalid request) are usually caused by the client and will not be fixed by retrying. A robust integration should distinguish between these categories, because retrying a malformed request wastes quota and delays the eventual failure the caller needs to see.

Rate limits themselves typically come in several dimensions, most commonly requests per minute and tokens per minute, and they generally apply per organization or per API key rather than per process. This matters in a Spring Boot deployment because horizontally scaled instances share the same underlying limit. When a 429 response is returned, the API commonly includes a Retry-After header indicating how long the client should wait. Honoring that value, rather than guessing, is the most reliable way to recover, and it appears to be the behavior Anthropic's documentation encourages.

On the implementation side, Spring offers several building blocks. Spring Retry, often used through the @Retryable annotation, provides declarative retries with configurable backoff policies and is straightforward to add to a service method. For more comprehensive fault tolerance, Resilience4j has largely replaced the now-deprecated Hystrix and integrates cleanly with Spring Boot through dedicated starters. It bundles retry, circuit breaker, rate limiter, bulkhead, and time limiter modules that can be composed together. A common pattern is to wrap the Claude client call in a retry decorator backed by a circuit breaker, so that repeated failures eventually trip the breaker and stop hammering an already-struggling endpoint.

The retry strategy deserves particular attention. Fixed-interval retries can create synchronized bursts of traffic, sometimes called the thundering herd problem, where many clients retry at the same moment and re-trigger the limit. Exponential backoff with jitter mitigates this by progressively lengthening the delay between attempts and adding a randomized component so that retries spread out over time. It is also important to cap the maximum number of attempts and the total elapsed time, since Claude requests, especially long completions, may be latency-sensitive and cannot wait indefinitely.

Exception handling ties these pieces together. Whether you call the API through the official Anthropic Java SDK, Spring's WebClient, or RestTemplate, translating raw HTTP failures into meaningful domain exceptions makes the surrounding code easier to reason about. A typical approach maps retryable conditions to a custom exception that the retry policy recognizes, while non-retryable errors propagate immediately. Spring's @ControllerAdvice with @ExceptionHandler can then convert those exceptions into consistent HTTP responses for downstream consumers, and structured logging or metrics around each retry attempt help operators diagnose whether failures are transient or systemic.

Several adjacent considerations round out a production setup. Timeouts should be configured explicitly, because model responses can take seconds and a hung connection ties up threads. WebClient's reactive, non-blocking model can be advantageous under high concurrency, though it introduces its own complexity compared with a blocking RestTemplate. Teams sometimes add a client-side rate limiter or token-bucket queue to stay under quota proactively rather than reacting to 429s, and caching identical prompts or deduplicating requests can reduce load further. For workloads that tolerate delay, Anthropic's Message Batches API is another option that shifts high-volume processing away from the synchronous path.

Taken together, these techniques are less about Claude specifically and more about disciplined external-service integration. The likely payoff is an application that degrades gracefully under throttling and outages, giving users predictable behavior instead of raw stack traces when the upstream model is unavailable.