Error Handling

Any call to the API can fail. When it does, the client raises an error instead of returning a result. Errors are organized in a hierarchy: a single base error for any client error, a more specific base for errors coming from the API, and then one error for each specific cause.

Base errors

Every error raised by the client inherits from a single base class. Catching it lets you handle any client error in one place.

A more specific base class is used for errors returned by the API itself. It carries the HTTP status code and the raw response body, which is useful for logging.

Code
try {
    Term result = client.intersection(List.of(a, b));
} catch (ApiException e) {
    System.out.println("API error " + e.getStatusCode() + ": " + e.getErrorCode());
} catch (RegexSolverException e) {
    System.out.println("Client error: " + e.getMessage());
}

Error reference

Each specific cause has its own error class, grouped below under the broader error it belongs to. Catching the broader one handles every cause listed with it, including causes added in future releases.

In Java, every class name ends with Exception (for example RegexSyntaxException). In the other SDKs it ends with Error (for example RegexSyntaxError). The names below are written without the suffix. Each one also corresponds to an errorCode in the API response body, spelled the same way, except RegexSyntax and FairSyntax, whose wire codes are RegexSyntaxError and FairSyntaxError.

Bad request (400)

Raised when the request itself is rejected. BadRequest on its own means the request was malformed for a reason the more specific errors do not cover.

Authentication and authorization (401, 403)

Everything else (404, 429, 500)

Handling specific cases

A common pattern is to handle one or two specific errors, such as an invalid pattern or an exhausted quota, and treat everything else as a generic failure.

Code
try {
    Term term = Term.regex(userProvidedPattern);
    Cardinality cardinality = client.getCardinality(term);
} catch (RegexSyntaxException e) {
    System.out.println("The pattern is not valid: " + e.getMessage());
} catch (QuotaExceededException e) {
    System.out.println("Monthly quota reached, try again later.");
}

Rate limiting

The client tracks your requests-per-second limit locally and, when the API still answers with a rate-limit response, transparently waits the server-indicated delay and retries, spreading concurrent retries so they do not collide. Rate-limit errors are never raised in normal operation, even when many requests are sent at the same time; the TooManyRequests error only surfaces after several minutes of unsuccessful retries. To get the most accurate rate limiting, follow the recommendation in Best Practices to use a single client per API token.

Oversized term lists

Your plan caps how many terms a single request may carry. With auto-batching enabled (the default), the client splits oversized union, intersection and concat calls into several requests and combines the results, so TooManyTerms is never raised. It only appears once you disable auto-batching. See Auto-Batching.