> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developers.meshapi.ai/docs/sd-ks/llms.txt.
> For full documentation content, see https://developers.meshapi.ai/docs/sd-ks/llms-full.txt.

# Java SDK

> Getting started with the MeshAPI Java SDK.

# Java SDK

A highly-performant, typed Java SDK for integrating MeshAPI into your Spring or Java 17+ applications.

## Requirements

* Java 17 or higher
* Maven 3.6 or higher

## Installation

Add MeshAPI as a dependency in your `pom.xml`:

```xml
<dependency>
  <groupId>com.meshapi.sdk</groupId>
  <artifactId>meshapi-java-sdk</artifactId>
  <version>0.1.0</version>
</dependency>
```

## Quick Start

Initialize the builder pattern provided by the MeshAPI class.

### Standard Chat Completion

```java
MeshAPI client = MeshAPI.builder()
    .baseUrl("https://api.meshapi.ai")
    .token("rsk_...")
    .build();

ChatCompletionResponse resp = client.chat().completions().create(
    ChatCompletionRequest.builder()
        .model("openai/gpt-4o-mini")
        .addMessage(ChatMessage.user("What is 2+2?"))
        .build()
);

System.out.println(resp.choices.get(0).message.content); // "4"
```

### Streaming Chat Completion

Streaming returns a structured `Iterator`.

```java
Iterator<ChatCompletionChunk> it = client.chat().completions().stream(params);

while (it.hasNext()) {
    ChatCompletionChunk chunk = it.next();
    if (!chunk.choices.isEmpty() && chunk.choices.get(0).delta != null) {
        System.out.print(chunk.choices.get(0).delta.content);
    }
}
```

## Error Handling

Like other MeshAPI SDKs, retries on transient errors are handled for you automatically (up to 3 retries with a maximum 30s timeout and variable jitter, supporting `Retry-After`).

You can configure error limits manually:

```java
MeshAPI client = MeshAPI.builder()
    .baseUrl("https://api.meshapi.ai")
    .token("rsk_...")
    .maxRetries(5)   // 0 to disable
    .timeoutMs(30000)
    .build();
```

If an error is fatal or limits are breached, `MeshAPIError` is thrown:

```java
try {
    resp = client.chat().completions().create(params);
} catch (MeshAPIError e) {
    System.out.println(e.getStatus());           // HTTP status
    System.out.println(e.getErrorCode());        // e.g. rate_limit_exceeded
    System.out.println(e.getRequestId());        // Traceable request ID
}
```

> \[!WARNING]
> **Streams do not automatically retry!** Ensure your `while(it.hasNext())` loop captures `MeshAPIError`s representing drops, such as the `stream_interrupted` error code.