Production-shaped HTTP clients for the Seller API. Use these patterns in your server-side code — never ship the API key to a browser or app client.
What this covers#
How to configure a reusable client per language, attach Bearer auth, set timeouts, and retry transient failures. Pair this with Environments and Idempotency.
Prerequisites#
- A sandbox or production Seller API key
- Server runtime only (your store backend, worker, or BFF)
- Base URL from your deployment config (
AVRIX_BASE_URL, usuallyhttps://api.avrix.io)
Client configuration#
Reuse one client (or session) per process. Prefer connection pooling and a
single place that injects Authorization and Accept.
# Prefer env vars — never hardcode secrets in source control
export AVRIX_API_KEY="avrix_sk_sbx_your_key_here"
export AVRIX_BASE_URL="https://api.avrix.io"| Language | Pattern |
|---|---|
| TypeScript | Shared fetch wrapper; set headers per call |
| Python | requests.Session with default headers and timeout |
| PHP | Guzzle client with base_uri and default headers |
| Go | Reused http.Client + context on every request |
| Java | java.net.http.HttpClient (reuse the builder instance) |
| C# | IHttpClientFactory named client via DI |
Retries and backoff#
Retry 429, 502, 503, and 504. Honour Retry-After when present.
Do not blindly retry non-idempotent writes without a stable
Idempotency-Key — see Idempotency.
# Retry manually on 429 / 5xx — read Retry-After from response headers
curl -s -D - "$AVRIX_BASE_URL/api/seller/v1/whoami" \
-H "Authorization: Bearer $AVRIX_API_KEY" | headRules of thumb#
- Cap retries (for example 3–5 attempts) with exponential backoff and jitter.
- Treat unknown outcomes after a timeout as retry with the same key, not a new order.
- Surface
X-Request-Idin your logs for support escalation. - Keep connect and overall request timeouts explicit (for example 10s connect, 30s request) so workers do not hang indefinitely.
Timeouts and cancellation#
- Go: pass
context.WithTimeoutinto everyNewRequestWithContext. - C#: prefer
IHttpClientFactoryso handlers and DNS refresh stay healthy; cancel withCancellationTokenfrom your request pipeline. - Java: set
connectTimeouton the client and per-request timeout onHttpRequest. - Python / PHP: set session/client
timeoutonce; do not rely on defaults.
What a production client must do#
| Behaviour | Why |
|---|---|
| Bearer auth on every call | Seller API rejects missing or malformed auth |
Stable Idempotency-Key on writes | Prevents duplicate fulfilment on retries |
| Preview before charge | Gate on canFulfill — never charge otherwise |
| Webhook HMAC verify | Reject forged deliveries before side effects |
Common mistakes#
- Creating a new TCP connection for every request (hurts latency and cold starts).
- Hardcoding the API key in source control.
- Retrying POST /orders with a new idempotency key after a network blip.
- Calling Avrix from the browser or a mobile/desktop app client with the secret key.
Next steps#
- Client & helpers — OpenAPI-generated clients and helper behaviours
- Secrets and config — rotation and env separation
- Rate limits — headers and fair usage