{"id":3088,"date":"2023-12-04T11:52:27","date_gmt":"2023-12-04T19:52:27","guid":{"rendered":"https:\/\/www.couchbase.com\/blog\/spring-webclient-429-ratelimit-errors\/"},"modified":"2023-12-04T11:52:27","modified_gmt":"2023-12-04T19:52:27","slug":"spring-webclient-429-ratelimit-errors","status":"publish","type":"post","link":"https:\/\/www.couchbase.com\/blog\/spring-webclient-429-ratelimit-errors\/","title":{"rendered":"Manage 429 RateLimit Errors with Spring WebClient"},"content":{"rendered":"\n

I have recently taken over the maintenance of a Spring Boot<\/a> project. This project has some RateLimit <\/em>errors in the logs when the app was contacting a remote REST API. Turns out that this app was also using the synchronous, blocking RestTemplate<\/em> client to make the API calls, instead of the newer Spring WebClient<\/em>, that happens to be using the Reactor API under the hood.<\/span><\/p>\n\n\n\n

And you know what is great about Reactor and using Reactive APIs in general? It makes programming with Data Stream so easy. Which also means it makes retry strategies implementation easier.<\/span><\/p>\n\n\n\n

Let’s talk about the error in the log first. What I got looked like this:<\/span><\/p>\n\n\n

[crayon nums=”false” nums-toggle=”false” lang=”default” decode=”true”]org.springframework.web.client.HttpClientErrorException$TooManyRequests: 429 Too Many Requests: [{“response_type”:”ERROR”,”message”:”Number of requests has exceeded the 1 minute limit”}]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.HttpClientErrorException.create(HttpClientErrorException.java:137) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.DefaultResponseErrorHandler.handleError(DefaultResponseErrorHandler.java:184) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.DefaultResponseErrorHandler.handleError(DefaultResponseErrorHandler.java:125) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.ResponseErrorHandler.handleError(ResponseErrorHandler.java:63) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.RestTemplate.handleResponse(RestTemplate.java:782) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.RestTemplate.doExecute(RestTemplate.java:740) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.RestTemplate.execute(RestTemplate.java:674) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.web.client.RestTemplate.getForObject(RestTemplate.java:315) ~[spring-web-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at com.couchbase.training.couchlms.repository.LmsRepository.getCourseModules(LmsRepository.java:102) ~[classes!\/:0.0.40-SNAPSHOT]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at com.couchbase.training.couchlms.services.LmsProcessor.processCourseModules(LmsProcessor.java:147) [classes!\/:0.0.40-SNAPSHOT]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at com.couchbase.training.couchlms.services.LmsProcessor.processCourses(LmsProcessor.java:91) [classes!\/:0.0.40-SNAPSHOT]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at com.couchbase.training.couchlms.config.SchedulingConfig.scheduledCoursesPuller(SchedulingConfig.java:45) [classes!\/:0.0.40-SNAPSHOT]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at sun.reflect.NativeMethodAccessorImpl.invoke0(Native Method) ~[na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at sun.reflect.NativeMethodAccessorImpl.invoke(NativeMethodAccessorImpl.java:62) ~[na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at sun.reflect.DelegatingMethodAccessorImpl.invoke(DelegatingMethodAccessorImpl.java:43) ~[na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.lang.reflect.Method.invoke(Method.java:498) ~[na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.scheduling.support.ScheduledMethodRunnable.run(ScheduledMethodRunnable.java:84) [spring-context-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at org.springframework.scheduling.support.DelegatingErrorHandlingRunnable.run(DelegatingErrorHandlingRunnable.java:54) [spring-context-5.2.9.RELEASE.jar!\/:5.2.9.RELEASE]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.util.concurrent.Executors$RunnableAdapter.call(Executors.java:511) [na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.util.concurrent.FutureTask.runAndReset(FutureTask.java:308) [na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.access$301(ScheduledThreadPoolExecutor.java:180) [na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.util.concurrent.ScheduledThreadPoolExecutor$ScheduledFutureTask.run(ScheduledThreadPoolExecutor.java:294) [na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.util.concurrent.ThreadPoolExecutor.runWorker(ThreadPoolExecutor.java:1149) [na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.util.concurrent.ThreadPoolExecutor$Worker.run(ThreadPoolExecutor.java:624) [na:1.8.0_252]
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0at java.lang.Thread.run(Thread.java:748) [na:1.8.0_252][\/crayon]<\/p>\n\n\n\n

As usual, the interesting bit in stack traces is at the top. The error is <\/span>429 Too Many Requests<\/strong>, and the message says there is a 1 minute rate limit<\/strong>. Decomposing this, the HTTP status<\/span>\u00a0code returned is 429<\/span><\/a>. It’s a Rate Limit error, meaning the API tells the caller it has sent too many request. This can usually be solved by waiting a bit, and you might even have a Retry-after<\/em>\u00a0header in the response telling you how long you have to wait. <\/span><\/p>\n\n\n\n

Let’s see how we can get that information with Spring’s WebClient:<\/span><\/p>\n\n\n

[crayon nums=”false” lang=”java” decode=”true”].uri(ub -> ub.pathSegment(uri).queryParams(queryParams).build())
\n.retrieve()
\n.onStatus(
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0HttpStatus.TOO_MANY_REQUESTS::equals,
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0response -> {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0List<String> header = response.headers().header(“Retry-After”);
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0Integer delayInSeconds;
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0if (!header.isEmpty()) {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0delayInSeconds = Integer.valueOf(header.get(0));
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0} else {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0delayInSeconds = 60;
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0}
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return response.bodyToMono(String.class).map(msg -> new RateLimitException(msg, delayInSeconds));
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0})
\n.bodyToMono(String.class)[\/crayon]<\/p>\n\n\n\n

This code is sending a GET<\/em> request. The WebClient allows us to take a look at the request’s response and react appropriately thanks to the onStatus<\/em> method. The first parameter is a boolean used to filter on returned HTTP Status code. Here, when the status code is 429, we do something.<\/p>\n\n\n\n

We take a look at the Response<\/em> headers, look if there is a Retry-After<\/em> header, if so, we initialize the delayInSeconds<\/em> variable with it, if not, we set a 60 default value. Then we can send back the Response<\/em> body mapped to a RateLimitException<\/em>. The body content will be used as an error message and the delayInSeconds will be available in a separate field. Take a look at the Exception code for more details:<\/span><\/p>\n\n\n

[crayon nums=”false” lang=”default” decode=”true”]import java.time.Duration;
\npublic class RateLimitException extends Throwable {
\n\u00a0\u00a0\u00a0\u00a0private int retryAfterDelay = 60;<\/p>\n

\u00a0\u00a0\u00a0\u00a0public RateLimitException(String message) {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0super(message);
\n\u00a0\u00a0\u00a0\u00a0}<\/p>\n

\u00a0\u00a0\u00a0\u00a0public RateLimitException(String message, int retryAfterDelay) {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0super(message); this.retryAfterDelay = retryAfterDelay;
\n\u00a0\u00a0\u00a0\u00a0}<\/p>\n

\u00a0\u00a0\u00a0\u00a0public int getRetryAfterDelay() {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return retryAfterDelay;
\n\u00a0\u00a0\u00a0\u00a0}<\/p>\n

\u00a0\u00a0\u00a0\u00a0public Duration getRetryAfterDelayDuration() {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return Duration.ofSeconds(retryAfterDelay);
\n\u00a0\u00a0\u00a0\u00a0}
\n}[\/crayon]<\/p>\n\n\n\n

So what needs to be done is catching this specific error and then retrying after the given duration. Reactor makes that easy by providing Retries<\/em> strategies. All you need to do is call the retryWhen<\/em> method:<\/span><\/p>\n\n\n

[crayon nums=”false” lang=”java” decode=”true”].bodyToMono(String.class)
\n.retryWhen(Retry.withThrowable(throwableFlux -> {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return throwableFlux.filter(t -> t instanceof RateLimitException).map(t -> {
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0RateLimitException rle = (RateLimitException) t;
\n\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0\u00a0return Retry.fixedDelay(1, rle.getRetryAfterDelayDuration());
\n\u00a0\u00a0\u00a0\u00a0});[\/crayon]<\/p>\n\n\n\n

There are different Retry<\/em> methods, here we can use the withThrowable()<\/em> builder. It gives a Flux that should contain the RateLimitException<\/em>. So we start by applying a filter to make sure of that. Then we map that exception to the actual Retry object. Here it’s the Retry.fixedDelay<\/em> strategy, taking a maximum attempts and duration as parameters. The duration comes from the RateLimitException<\/em> that was thrown earlier.<\/span><\/p>\n\n\n\n

With that, each time a request returns a 429, the client will wait the appropriate time until it retries. And it was much easier to implement with Reactor than using try\/catch<\/em> with Spring’s RestTemplate<\/em>. I know Reactive programming might be a little intimidating at first, but it’s a great way to manage data streams like HTTP requests and responses, or to manage connections to databases that support reactive programming, like Couchbase<\/a>.<\/span><\/p>\n\n\n\n

Want some more help and ideas?<\/p>\n\n\n\n