> ## 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/tree/master/telnyx-java-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/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/BadRequestException.kt)                     |
  | 401    | [`UnauthorizedException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/UnauthorizedException.kt)                 |
  | 403    | [`PermissionDeniedException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/PermissionDeniedException.kt)         |
  | 404    | [`NotFoundException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/NotFoundException.kt)                         |
  | 422    | [`UnprocessableEntityException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/UnprocessableEntityException.kt)   |
  | 429    | [`RateLimitException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/RateLimitException.kt)                       |
  | 5xx    | [`InternalServerException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/InternalServerException.kt)             |
  | others | [`UnexpectedStatusCodeException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/errors/UnexpectedStatusCodeException.kt) |

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

* [`TelnyxRetryableException`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-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/tree/master/telnyx-java-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/tree/master/telnyx-java-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.

## Network options

### 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.calls.CallDialResponse;

CallDialResponse response = client.calls().dial(
  params, 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();
```

### Proxies

To route requests through a proxy, configure the client using the `proxy` method:

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

TelnyxClient client = TelnyxOkHttpClient.builder()
    .fromEnv()
    .proxy(new Proxy(
      Proxy.Type.HTTP, new InetSocketAddress(
        "https://example.com", 8080
      )
    ))
    .build();
```

### HTTPS

> \[!NOTE]
> Most applications should not call these methods, and instead use the system defaults. The defaults include
> special optimizations that can be lost if the implementations are modified.

To configure how HTTPS connections are secured, configure the client using the `sslSocketFactory`, `trustManager`, and `hostnameVerifier` methods:

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

TelnyxClient client = TelnyxOkHttpClient.builder()
    .fromEnv()
    // If `sslSocketFactory` is set, then `trustManager` must be set, and vice versa.
    .sslSocketFactory(yourSSLSocketFactory)
    .trustManager(yourTrustManager)
    .hostnameVerifier(yourHostnameVerifier)
    .build();
```

### Custom HTTP client

The SDK consists of three artifacts:

* `telnyx-java-core`
  * Contains core SDK logic
  * Does not depend on [OkHttp](https://square.github.io/okhttp)
  * Exposes [`TelnyxClient`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClient.kt), [`TelnyxClientAsync`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientAsync.kt), [`TelnyxClientImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientImpl.kt), and [`TelnyxClientAsyncImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientAsyncImpl.kt), all of which can work with any HTTP client
* `telnyx-java-client-okhttp`
  * Depends on [OkHttp](https://square.github.io/okhttp)
  * Exposes [`TelnyxOkHttpClient`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/TelnyxOkHttpClient.kt) and [`TelnyxOkHttpClientAsync`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/TelnyxOkHttpClientAsync.kt), which provide a way to construct [`TelnyxClientImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientImpl.kt) and [`TelnyxClientAsyncImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientAsyncImpl.kt), respectively, using OkHttp
* `telnyx-java`
  * Depends on and exposes the APIs of both `telnyx-java-core` and `telnyx-java-client-okhttp`
  * Does not have its own logic

This structure allows replacing the SDK's default HTTP client without pulling in unnecessary dependencies.

#### Customized [`OkHttpClient`](https://square.github.io/okhttp/3.x/okhttp/okhttp3/OkHttpClient.html)

> \[!TIP]
> Try the available [network options](#network-options) before replacing the default client.

To use a customized `OkHttpClient`:

1. Replace your [`telnyx-java` dependency](/docs/development/sdk/java#install) with `telnyx-java-core`
2. Copy `telnyx-java-client-okhttp`'s [`OkHttpClient`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/OkHttpClient.kt) class into your code and customize it
3. Construct [`TelnyxClientImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientImpl.kt) or [`TelnyxClientAsyncImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientAsyncImpl.kt), similarly to [`TelnyxOkHttpClient`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/TelnyxOkHttpClient.kt) or [`TelnyxOkHttpClientAsync`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/TelnyxOkHttpClientAsync.kt), using your customized client

### Completely custom HTTP client

To use a completely custom HTTP client:

1. Replace your [`telnyx-java` dependency](/docs/development/sdk/java#install) with `telnyx-java-core`
2. Write a class that implements the [`HttpClient`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/core/http/HttpClient.kt) interface
3. Construct [`TelnyxClientImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientImpl.kt) or [`TelnyxClientAsyncImpl`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-core/src/main/kotlin/com/telnyx/sdk/client/TelnyxClientAsyncImpl.kt), similarly to [`TelnyxOkHttpClient`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/TelnyxOkHttpClient.kt) or [`TelnyxOkHttpClientAsync`](https://github.com/team-telnyx/telnyx-java/tree/master/telnyx-java-client-okhttp/src/main/kotlin/com/telnyx/sdk/client/okhttp/TelnyxOkHttpClientAsync.kt), using your new client class