> ## Documentation Index
> Fetch the complete documentation index at: https://developers.telnyx.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Java SDK errors, retries, and timeouts

> Exception hierarchy and network options — retries, timeouts, and proxies — in the Telnyx Java SDK.

## Error handling

The SDK throws custom unchecked exception types:

* [`TelnyxServiceException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/TelnyxServiceException.kt): Base class for HTTP errors. See this table for which exception subclass is thrown for each HTTP status code:

  | Status | Exception |
  | - | - |
  | 400 | [`BadRequestException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/BadRequestException.kt) |
  | 401 | [`UnauthorizedException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/UnauthorizedException.kt) |
  | 403 | [`PermissionDeniedException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/PermissionDeniedException.kt) |
  | 404 | [`NotFoundException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/NotFoundException.kt) |
  | 422 | [`UnprocessableEntityException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/UnprocessableEntityException.kt) |
  | 429 | [`RateLimitException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/RateLimitException.kt) |
  | 5xx | [`InternalServerException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/InternalServerException.kt) |
  | others | [`UnexpectedStatusCodeException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/UnexpectedStatusCodeException.kt) |

* [`TelnyxIoException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/TelnyxIoException.kt): I/O networking errors.

* [`TelnyxRetryableException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/TelnyxRetryableException.kt): Generic error indicating a failure that could be retried by the client.

* [`TelnyxInvalidDataException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/TelnyxInvalidDataException.kt): Failure to interpret successfully parsed data. For example, when accessing a property that's supposed to be required, but the API unexpectedly omitted it from the response.

* [`TelnyxException`](https://github.com/team-telnyx/telnyx-java/blob/master/telnyx-core/src/main/kotlin/com/telnyx/sdk/errors/TelnyxException.kt): Base class for all exceptions. Most errors will result in one of the previously mentioned ones, but completely generic errors may be thrown using the base class.

## Retries

The SDK automatically retries 2 times by default, with a short exponential backoff between requests.

Only the following error types are retried:

* Connection errors (for example, due to a network connectivity problem)
* 408 Request Timeout
* 409 Conflict
* 429 Rate Limit
* 5xx Internal

The API may also explicitly instruct the SDK to retry or not retry a request.

To set a custom number of retries, configure the client using the `maxRetries` method:

```java theme={null}
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;

TelnyxClient client = TelnyxOkHttpClient.builder()
    .fromEnv()
    .maxRetries(4)
    .build();
```

## Timeouts

Requests time out after 1 minute by default.

To set a custom timeout, configure the method call using the `timeout` method:

```java theme={null}
import com.telnyx.sdk.models.numberorders.NumberOrderCreateResponse;

NumberOrderCreateResponse numberOrder = client.numberOrders().create(RequestOptions.builder().timeout(Duration.ofSeconds(30)).build());
```

Or configure the default for all method calls at the client level:

```java theme={null}
import com.telnyx.sdk.client.TelnyxClient;
import com.telnyx.sdk.client.okhttp.TelnyxOkHttpClient;
import java.time.Duration;

TelnyxClient client = TelnyxOkHttpClient.builder()
    .fromEnv()
    .timeout(Duration.ofSeconds(30))
    .build();
```