Retries & Errors¶

Retries¶

Failed requests are retried automatically. RetryPolicy's defaults match TypeSafe's official JS SDK:

The Python SDK shares these retries, backoff, jitter and statuses, but doesn't cap server hints, and it also gives each call a 30 s budget in total. jev4k has no total budget: timeout applies to each attempt, so a call that retries on long server hints can take a couple of minutes.

RetryPolicy.NONE turns retries off. The Configuration page shows common variations.

Other 4xx errors, such as a bad key or an invalid request, are never retried: retrying can't fix them.

Errors¶

Every failure of a request or a response is a JevException:

Messages include the status and request id, and never the API key. Header names in headers are lowercased, so e.headers["retry-after"] finds the header however the server spelled it and whichever engine read it.

A redirect isn't followed, so a 3xx arrives as a plain JevApiException. A response declaring a body over 16 MiB is refused unread: a 2xx as a JevResponseValidationException, anything else as its status's exception with a null body, the message saying why. A body without a declared length, which on Linux, Apple platforms and Node.js includes a compressed one, isn't checked; see Configuration.

Some problems with a 2xx surface only when an answer is read, so the other answers stay readable: a missing answer, a Box whose edges or confidence are out of range or whose edges are out of order, and an option the question never declared, read through enumChoice with a broader enum. Each raises JevResponseValidationException.

On Linux and Windows, any bare IllegalStateException raised during a call is also a JevConnectionException, because that is how the Curl and WinHttp engines report a failed connection; the original is kept as its cause.

Misusing a result is a programming error, not a JevException: asking for an id or handle that wasn't in the request, reading a Noul as a Choice, or reading a Choice with an enum that lacks one of its options throws IllegalArgumentException.

Handling errors¶

suspend fun triageOrNull(
    jev: JevApi,
    ticket: String,
): JevResult? =
    try {
        jev.ask(Triage, state = ticket)
    } catch (e: JevAuthenticationException) {
        throw IllegalStateException("Check TYPESAFE_API_KEY", e)
    } catch (e: JevRateLimitException) {
        // Already retried per the RetryPolicy; back off further before trying again.
        println("rate limited; server suggests waiting ${e.retryAfter}")
        null
    } catch (e: JevTimeoutException) {
        println("timed out: ${e.message}")
        null
    } catch (e: JevConnectionException) {
        println("no response from TypeSafe: ${e.message}")
        null
    } catch (e: JevApiException) {
        // Every other HTTP error: status, raw body, and the request id for support.
        println("HTTP ${e.status} (request ${e.requestId}): ${e.body}")
        null
    }

Or map any failure to a description with a when:

when (e) {
    is JevValidationException -> "invalid request: ${e.problems}"
    is JevUnprocessableEntityException -> "server rejected the request: ${e.bodyJson}"
    is JevOverloadedException -> "TypeSafe is overloaded (529); try again shortly"
    is JevResponseValidationException -> "unusable response at ${e.fieldPath}"
    is JevApiException -> "HTTP ${e.status} from ${e.endpoint}"
    is JevConnectionException -> "network problem: ${e.message}"
    else -> e.message ?: e.toString()
}

Validation errors¶

Local validation reports every problem at once, before anything is sent:

try {
    jev.query(state = "Is this spam?") {
        noul("spam", "")                                             // blank instructions
        score("severity", "How severe?") { level("only one level") } // a Score needs 2..10 levels
    }
} catch (e: JevValidationException) {
    // Nothing was sent. Every problem is listed at once.
    e.problems.forEach(::println)
}