Retries & idempotency

Automatic retries

Both SDKs retry failed requests automatically. By default they retry up to twice. A retry happens when:

• A connection error or timeout occurs
• The server responds with 408, 429, or any 5xx status other than 501

A retry never happens on 409 or 501.

Backoff is exponential with full jitter, so successive attempts spread out over time rather than hammering the server in lockstep. When the failing response is a 429, the backoff respects the Retry-After header — the SDK will not retry before the window it specifies has elapsed.

Per-call overrides

The default retry count is set at the client level and can be overridden for a single call.

const bimpe = new BimpeAI({ apiKey: '…', maxRetries: 3 });
await bimpe.agents.create(body, { maxRetries: 0 }); // this call only

client = BimpeAI(api_key="sk_...", max_retries=3)
client.agents.create(name="A", max_retries=0)  # this call only

Idempotency keys

Write requests accept an idempotency key. When retries are on and you do not supply a key, the SDK generates one for the call and reuses it across all retry attempts. A retried write therefore cannot create a duplicate — the server treats the second attempt as a replay of the first and returns the same result without applying the operation again. The key is sent as the Idempotency-Key header on write requests only.

Supply your own key when you want to control idempotency across sessions or restarts.

await bimpe.agents.create({ name: 'A' }, { idempotencyKey: 'create-A-2026-06-14' });

client.agents.create(name="A", idempotency_key="create-A-2026-06-14")