Java SDK

The com.zeridion:flare package is published on Maven Central. HTTP via stdlib java.net.http.HttpClient; JSON via jackson-databind (single transitive dep).

Maven:

<dependency>
    <groupId>com.zeridion</groupId>
    <artifactId>flare</artifactId>
    <version>0.1.0</version>
</dependency>

Gradle (Kotlin DSL):

implementation("com.zeridion:flare:0.1.0")

Requires: Java 17+ (LTS).

Quick start

import com.zeridion.flare.FlareClient;
import com.zeridion.flare.FlareException;
import com.zeridion.flare.RateLimitException;
import java.util.Map;

FlareClient client = FlareClient.builder()
    .apiKey("zf_live_sk_...")
    .build();
// Or, with FLARE_API_KEY set in the environment:
//     FlareClient client = FlareClient.builder().build();

try {
    Map<String, Object> job = client.createJob(Map.of(
        "job_type", "SendWelcomeEmail",
        "payload", Map.of("email", "alice@example.com"),
        "queue", "default"
    ));

    System.out.println(job.get("id") + " " + job.get("state"));  // "job_abc123 pending"
} catch (RateLimitException e) {
    // 429 — back off until e.getRetryAfter() (epoch seconds)
    System.err.println("rate limited, retry-after=" + e.getRetryAfter());
} catch (FlareException e) {
    // 401 / 402 / 404 / 409 / 5xx all subclass FlareException
    System.err.println("flare error: " + e.getCode() + " (" + e.getStatusCode() + ")");
}

Client construction

FlareClient client = FlareClient.builder()
    .apiKey("zf_live_sk_...")
    .baseUrl("https://api.zeridion.com")  // override for dev / staging
    .maxRetries(3)                         // 0 to disable retries
    .retryBaseDelay(Duration.ofMillis(500))
    .retryMaxDelay(Duration.ofSeconds(30))
    .timeout(Duration.ofSeconds(30))
    .maxResponseBytes(10L * 1024 * 1024)   // 10 MiB cap (0 disables)
    .build();

The default per-request timeout is 30 seconds. Override it via .timeout(Duration.ofSeconds(...)) on the builder; the value is applied to every outbound HTTP request the client makes.

Typed error hierarchy

Class	HTTP	When it fires
`FlareException`	—	Base class for every SDK exception
`AuthException`	401	Missing / invalid / revoked API key
`QuotaException`	402	Daily quota exceeded
`NotFoundException`	404	Resource doesn't exist
`ConflictException`	409	Idempotency or invalid-state conflict
`RateLimitException`	429	Inspect `getRetryAfter()`, `getLimit()`, `getRemaining()`

All exceptions extend FlareException so a single catch is sufficient when granularity isn't needed.

Method reference

Each method returns a Map<String, Object> deserialised from the JSON response body, or null for the documented non-throwing 404 / 409 cases. Every method also has a one-arg overload (omit RequestOptions).

client.createJob(body, opts);    // POST /flare/v1/jobs
client.getJob(jobId, opts);      // GET  /flare/v1/jobs/{id}     — returns null on 404
client.listJobs(filters, opts);  // GET  /flare/v1/jobs          — cursor-paginated
client.cancelJob(jobId, opts);   // POST /flare/v1/jobs/{id}/cancel — returns null on 409
client.retryJob(jobId, opts);    // POST /flare/v1/jobs/{id}/retry  — returns null on 409
client.pollWorkers(body, opts);  // POST /flare/v1/workers/poll
client.ackWorker(body, opts);    // POST /flare/v1/workers/ack

RequestOptions carries optional idempotencyKey (sent as Idempotency-Key) and requestId (sent as X-Request-Id) header values; both can be omitted via the client.foo(body) one-arg overload.

Feature parity

See the SDK overview for the full feature-parity matrix across all 7 official SDKs.

Source

github.com/zeridion/flare-java

Quick start​

Client construction​

Typed error hierarchy​

Method reference​

Feature parity​

Source​

See also​