Package discord4j.rest.http.client

Class ClientException

java.lang.Object

java.lang.Throwable

java.lang.Exception

java.lang.RuntimeException

discord4j.rest.http.client.ClientException

All Implemented Interfaces:

Serializable

public class ClientException
extends RuntimeException

Exception that contains information about a failed request containing HTTP response data.

The original request can be retrieved through getRequest(). HTTP response status can be retrieved by getStatus(), headers using getHeaders(), while the body can be retrieved through getErrorResponse() provided Discord has supplied a body along with the error.

It is possible to modify the behavior of a reactive sequence that has failed with this error, using operators like Mono.onErrorResume(Predicate, Function), Mono.onErrorContinue(Predicate, BiConsumer) among others. In cases where a Predicate is accepted, you can use one of the provided static methods like isStatusCode(int) to further filter by HTTP status code.

The following example would retry a request if it has failed with an HTTP 500 error:

 client.getEventDispatcher().on(MessageCreateEvent.class)
     .map(MessageCreateEvent::getMessage)
     .filter(msg -> msg.getContent().map("!ping"::equals).orElse(false))
     .flatMap(Message::getChannel)
     .flatMap(channel -> channel.createMessage("Pong!")
         .transform(ClientException.retryOnceOnStatus(500)))
     .subscribe();
 

While the following one would transform a not found user into an empty sequence:

 client.getUserById(Snowflake.of(userLongId))
     .onErrorResume(ClientException.isStatusCode(404), error -> Mono.empty())
     .subscribe(user -> System.out.println("Found: " + user.getUsername()));
 

For global or Route based error handling, refer to the ResponseFunction class.

See Also:

Serialized Form

Constructor Summary

Constructors

Constructor	Description
ClientException(ClientRequest request, HttpClientResponse response, ErrorResponse errorResponse)	Create a new ClientException with the given HTTP request and response details.

Method Summary

Modifier and Type	Method	Description
static <T> Function<Mono<T>,Publisher<T>>	emptyOnStatus(int code)	Transformation function that can be used within an operator such as Mono.transform(Function) or Mono.transformDeferred(Function) to turn an error sequence matching the given HTTP status code, into an empty sequence, effectively suppressing the original error.
Optional<ErrorResponse>	getErrorResponse()	Return the HTTP response body in the form of a Discord ErrorResponse, if present.
HttpHeaders	getHeaders()	Return the HttpHeaders from the error response.
ClientRequest	getRequest()	Return the ClientRequest encapsulating a Discord API request.
HttpClientResponse	getResponse()	Return the HttpClientResponse encapsulating a low-level Discord API response.
HttpResponseStatus	getStatus()	Return the HttpResponseStatus with information related to the HTTP error.
static Predicate<RetryContext<?>>	isRetryContextStatusCode(int code)	Predicate helper to further classify a ClientException, while creating a Retry factory, depending on the underlying HTTP status code.
static Predicate<RetryContext<?>>	isRetryContextStatusCode(Integer... codes)	Predicate helper to further classify a ClientException, while creating a Retry factory, depending on the underlying HTTP status code.
static Predicate<Throwable>	isStatusCode(int code)	Predicate helper to further classify a ClientException depending on the underlying HTTP status code.
static Predicate<Throwable>	isStatusCode(Integer... codes)	Predicate helper to further classify a ClientException depending on the underlying HTTP status code.
static <T> Function<Mono<T>,Publisher<T>>	retryOnceOnStatus(int code)	Transformation function that can be used within an operator such as Mono.transform(Function) or Mono.transformDeferred(Function) to apply a retrying strategy in case of an error matching the given HTTP status code.

Methods inherited from class java.lang.Throwable

addSuppressed, fillInStackTrace, getCause, getLocalizedMessage, getMessage, getStackTrace, getSuppressed, initCause, printStackTrace, printStackTrace, printStackTrace, setStackTrace, toString

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ClientException

public ClientException(ClientRequest request,
                       HttpClientResponse response,
                       @Nullable
                       ErrorResponse errorResponse)

Create a new ClientException with the given HTTP request and response details.

Parameters:

request - the original ClientRequest that caused this exception

response - the failing HttpClientResponse

errorResponse - the response body converted to an ErrorResponse, or null if not available

Method Detail

getRequest

public ClientRequest getRequest()

Return the ClientRequest encapsulating a Discord API request.

Returns:

the request that caused this exception

getResponse

public HttpClientResponse getResponse()

Return the HttpClientResponse encapsulating a low-level Discord API response.

Returns:

the low-level response that caused this exception

getStatus

public HttpResponseStatus getStatus()

Return the HttpResponseStatus with information related to the HTTP error. The actual status code can be obtained through HttpResponseStatus.code().

Returns:

the HTTP error associated to this exception

getHeaders

public HttpHeaders getHeaders()

Return the HttpHeaders from the error response. To get request headers refer to getRequest() and then ClientRequest.getHeaders().

Returns:

the HTTP response headers

getErrorResponse

public Optional<ErrorResponse> getErrorResponse()

Return the HTTP response body in the form of a Discord ErrorResponse, if present. ErrorResponse is a common object that contains an internal status code and messages, and could be used to further clarify the source of the API error.

Returns:

the Discord error response, if present

isStatusCode

public static Predicate<Throwable> isStatusCode(int code)

Predicate helper to further classify a ClientException depending on the underlying HTTP status code.

Parameters:

code - the status code for which this Predicate should return true

Returns:

a Predicate that returns true if the given Throwable is a ClientException containing the given HTTP status code

isStatusCode

public static Predicate<Throwable> isStatusCode(Integer... codes)

Predicate helper to further classify a ClientException depending on the underlying HTTP status code.

Parameters:

codes - the status codes for which this Predicate should return true

Returns:

a Predicate that returns true if the given Throwable is a ClientException containing the given HTTP status code

isRetryContextStatusCode

public static Predicate<RetryContext<?>> isRetryContextStatusCode(int code)

Predicate helper to further classify a ClientException, while creating a Retry factory, depending on the underlying HTTP status code. A Retry factory can be created through methods like Retry.onlyIf(Predicate) where this method can be used as argument.

Parameters:

code - the status code for which this Predicate should return true

Returns:

a Predicate that returns true if the given RetryContext exception is a ClientException containing the given HTTP status code

isRetryContextStatusCode

public static Predicate<RetryContext<?>> isRetryContextStatusCode(Integer... codes)

Predicate helper to further classify a ClientException, while creating a Retry factory, depending on the underlying HTTP status code. A Retry factory can be created through methods like Retry.onlyIf(Predicate) where this method can be used as argument.

Parameters:

codes - the status codes for which this Predicate should return true

Returns:

a Predicate that returns true if the given Throwable is a ClientException containing the given HTTP status code

emptyOnStatus

public static <T> Function<Mono<T>,Publisher<T>> emptyOnStatus(int code)

Transformation function that can be used within an operator such as Mono.transform(Function) or Mono.transformDeferred(Function) to turn an error sequence matching the given HTTP status code, into an empty sequence, effectively suppressing the original error.

Type Parameters:

T - the type of the response

Parameters:

code - the status code that should be transformed into empty sequences

Returns:

a transformation function that converts error sequences into empty sequences

retryOnceOnStatus

public static <T> Function<Mono<T>,Publisher<T>> retryOnceOnStatus(int code)

Transformation function that can be used within an operator such as Mono.transform(Function) or Mono.transformDeferred(Function) to apply a retrying strategy in case of an error matching the given HTTP status code. The provided retrying strategy will wait 1 second, and then retry once.

Type Parameters:

T - the type of the response

Parameters:

code - the status code that should be retried

Returns:

a transformation function that retries error sequences