Why are timeouts not retried when everything else is?

Because a timed-out POST to the systemone endpoint may already have been processed and billed, and there is no idempotency key to make a second attempt safe. Retrying by default risks charging you twice for one decision. You opt in with retry: [api_timeout_error: true] if you accept that risk.

Is there a single error struct I can rescue against?

No, and the README is deliberate about it: the ten status-mapped structs and the generic error are unrelated exceptions with no shared base. Match on {:error, exception} for a catch-all clause, and note that Exception.message/1 works on all of them.

What happens under concurrency once the connection pool is full?

Req's default pool keeps 50 connections per host, and each request holds one for its whole round trip. Extra concurrent calls wait up to Finch's 5-second pool timeout, then return a connection error with reason pool_timeout rather than a timeout error. That is never retried, since a retry would just queue behind the same busy pool, so size the pool with finch: [size: n].

Does the timeout value bound the whole call?

No. It applies per attempt, not to the call end to end, and it is passed through as Req's receive_timeout, which limits the wait for each individual read from the socket. A response that trickles in slowly can therefore run past it, and connecting is governed separately by Finch's default, adjustable through connect_options.

How do I create a client and send a decision?

Set TYPESAFE_API_KEY, call TypeSafe.new(), then TypeSafe.system_one(client, %{state: %{document: ...}, questions: %{category: TypeSafe.choice(...)}}). Read the answer with response["answers"]["category"]["choice"]; helpers noul, choice and score build the typed questions.

What options does the client take, and where do they fall back?

TypeSafe.new/1 accepts api_key, base_url, default_model and log_level, each falling back to its TYPESAFE_* environment variable. base_url, default_model and log_level then fall back to defaults, but api_key has none and new/1 returns an error without one.

How does the retry backoff work?

By default a failed request is retried up to 2 times on a 408, 429, 5xx or connection error, waiting 500 ms then 1000 ms capped at 5000 ms with up to 25% jitter. A Retry-After or retry-after-ms header is honored exactly when it is at most max_retry_after_ms, 60 seconds by default.

CommunityJev Repos & SDKs

TypeSafe SDK Ex

An unofficial Elixir SDK for TypeSafe's System One endpoint, built on Req and Finch, with per-call retry policies, a shared connection pool and status-mapped errors.

See highlights

Open github.com

Stars: 1
Language: Elixir
Published by: Community
Author: vinnie357
Last verified: Oct 2026

vinnie357/typesafe_sdk_ex

User repository on GitHub

View on GitHub

Typesafe AI SDK in Elixir using Req

Forks: 0
Last pushed: Updated Oct 2026

Repo stats from the GitHub API, cached Oct 2026.

About this project

typesafeai sdk in elixir using req based on: Set TYPESAFEAPIKEY in your environment, then create and use the client:

Quoted from the project's README. Read the full README.

Tagscommunity jevbest catalog-import awesomejev

Works forJev for Classification

Used inJev for Software & DevTools

Languages: Elixir

Highlights

It mirrors the JavaScript SDK's surface: a new/1 client, system_one/3, the noul, choice and score helpers, and list_models, all keyed off TYPESAFE_API_KEY.
Ten error structs are mapped from HTTP status, including one carrying retry_after_ms for rate limits, plus separate structs for connection and timeout failures.
Retries default to two attempts on 408, 429, 5xx and connection errors with jittered backoff, overridable per call without mutating the client.
Requests share a Finch pool and hold one connection for the whole round trip, with pool sizing and pool timeout exposed as options.

Watch out

This is an unofficial port of the JS SDK, not TypeSafe's own Elixir client, so parity with the upstream surface is maintained by whoever maintains this repo. Timeout handling is deliberately conservative: a POST to the systemone endpoint that timed out may already have been processed and billed, and the API has no idempotency key, so timeouts are not retried unless you opt in. The timeout value applies per attempt and maps to Req's receive_timeout, which bounds each socket read rather than the call, so a slow-trickling response can outlast it; connecting is bounded separately by Finch's own default. Pool exhaustion returns a connection error with reason pool_timeout and is never retried under any policy. Raising the Retry-After ceiling makes a single call sleep that long before retrying. The error structs deliberately share no base struct, so pattern matching is the only way to catch them broadly. Copy reviewed against the repository README on 2026-10-04, not from running it.

Questions about this entry

Short answers drawn from the linked project or page.

More Jev resources like this

typesafe_ai

Elixir client for the TypeSafe AI System One API: supervised Mint HTTP/1 and HTTP/2 connections, bounded concurrency, request deadlines, retries and telemetry, with typed Choice, Score and Noul answers.