Error Handling and Rate Limits

Error Handling and Rate Limits

RestActionException

When Guilded rejects a request, you get a RestActionException (through the failure consumer of queue(), as the exception thrown by complete(), or as the cause of the failed submit() future). It has:

Method	Description
getStatusCode()	The HTTP status code, or -1 if the request never got a response
getErrorCode()	Guilded's error code, e.g. ForbiddenError or NotFoundError (can be null)
getMessage()	Includes the status, the code and the message Guilded sent
isRateLimited()	true for HTTP 429
getRetryAfterMillis()	How long Guilded asked us to wait for a 429, or -1

channel.sendMessage("hello").queue(
        message -> {},
        error -> {
            if (error instanceof RestActionException e && e.getStatusCode() == 403) {
                System.out.println("I'm not allowed to talk in that channel!");
            } else {
                error.printStackTrace();
            }
        }
);

Common status codes

Code	Meaning
400	The request was unacceptable, often due to missing parameters
401	The token is missing or invalid
403	The bot doesn't have the permissions for this
404	The thing you asked for doesn't exist
409	The request conflicted with another request
429	You are being rate limited
5xx	Something is wrong on Guilded's side, try again later

Other exceptions

• IOException - the request could not be made at all (no internet, timeout, ...). queue() passes it to your failure consumer.
• RestActionException is also used when the response of a successful request can't be understood.
• ClientBuildException - thrown by ClientBuilder#build() when there is no token.

Rate limits

• Actions that go through queue() are processed one after the other, around ten per second at most.
• When Guilded answers with a 429, the queue waits for the time Guilded asked for (one second if it didn't say) and tries again, up to 5 times. Only then your failure consumer is called.
• complete() and submit() do not retry, you get the 429 as an exception.
• For heavy work, switch to the throttled queue with jg_api.setQueueEnabled(true), see RestActions.

Exceptions inside your own code

If one of your consumers or event handlers throws, the exception is printed and the library keeps running. One listener failing doesn't stop other listeners from receiving the event.

Gateway disconnects

If the connection to the Guilded gateway drops, JG_API reconnects automatically (waiting 2 seconds, doubling up to 60 seconds between attempts) and asks Guilded to replay the events that were missed. ReadyEvent is only fired once. Calling jg_api.shutdown() closes the connection and doesn't reconnect.