API clients

Production HTTP client patterns per language — config, reuse, and retries.

TopicsReference

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, usually https://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"
LanguagePattern
TypeScriptShared fetch wrapper; set headers per call
Pythonrequests.Session with default headers and timeout
PHPGuzzle client with base_uri and default headers
GoReused http.Client + context on every request
Javajava.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" | head

Rules 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-Id in 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.WithTimeout into every NewRequestWithContext.
  • C#: prefer IHttpClientFactory so handlers and DNS refresh stay healthy; cancel with CancellationToken from your request pipeline.
  • Java: set connectTimeout on the client and per-request timeout on HttpRequest.
  • Python / PHP: set session/client timeout once; do not rely on defaults.

What a production client must do#

BehaviourWhy
Bearer auth on every callSeller API rejects missing or malformed auth
Stable Idempotency-Key on writesPrevents duplicate fulfilment on retries
Preview before chargeGate on canFulfill — never charge otherwise
Webhook HMAC verifyReject 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#

What links here

Published guides that link to this page.

Search docs

Search documentation…