EN SDK Retries and Errors

SDK retries, response limits and errors

English · Türkçe · Languages / Diller

Scope: JSON API Forge 0.5.1 · Source review: 17 September 2026 · Language: English

Retries are disabled by default. Supplying retry_policy=RetryPolicy(...) enables bounded attempts. max_attempts includes the first request: 3 means the initial call plus at most two retries.

import os
from json_api_forge import ForgeClient, RetryPolicy, ForgeHTTPError, ForgeTransportError

policy = RetryPolicy(max_attempts=3, backoff_seconds=0.2, max_backoff_seconds=2.0)
with ForgeClient("https://api.example.com", api_key=os.environ["FORGE_API_KEY"], retry_policy=policy) as forge:
    try:
        result = forge.list_items("wiki-demo", "items", params={"limit": 20})
    except ForgeHTTPError as exc:
        print("HTTP:", exc.status_code, "request:", exc.request_id)
    except ForgeTransportError:
        print("Server unreachable or request timed out")

Policy verified in code

Case	SDK behavior
GET/HEAD/OPTIONS/PUT/DELETE	Method is eligible when a retry policy is configured
POST/PATCH and other methods	Require idempotency_key
Request containing files	No automatic retry
Retryable HTTP statuses	Defaults: 408, 425, 429, 502, 503, 504
Transport failure	Retry when policy, method and attempt bounds permit
Oversized response	ForgeResponseTooLarge; no automatic retry

Older PYTHON_LIBRARY.md prose requiring a key for DELETE differs from the code. This Wiki follows RetryPolicy.permits and cluster _failover_permitted. If the first DELETE succeeded but its response was lost, a repeated DELETE can return 404. An idempotent method does not promise identical responses on every attempt.

Adding a header to POST does not implement server-side idempotency. Generic CRUD creation does not inherit the RPC ledger guarantee. Retriable side effects need an actual idempotency=true operation or equivalent business contract.

Backoff

Defaults are 0.2 seconds initial delay, 2.0 seconds maximum, multiplier 2.0 and jitter 0.15. max_attempts is bounded to 1–10. Numeric Retry-After values are capped. v0.5.1 delay does not parse HTTP-date format; unparseable values fall back to ordinary backoff.

Responses and observers

ForgeResponse contains data, status_code, request_id, idempotent_replay and cache_status. An observer receives a RequestAttempt for each attempt: method, path without query, attempt number, elapsed time, status, request ID and error. Observer failures are intended not to change the request result; keep callbacks short and free of secrets.

Transport defaults

Remote HTTPS is required. Redirects are not followed, trust_env=False, and cookies are not retained. The default response limit is 8 MiB. Requests use Accept-Encoding: identity; unsolicited compressed responses are rejected with ForgeHTTPError. Your proxy must respect that header. Review data volume and memory budgets before increasing limits.

Exception hierarchy

ForgeError is the base. ForgeHTTPError covers HTTP errors/incompatible responses; ForgeTransportError network failures; ForgeResponseTooLarge size limits; ForgeSessionError management sessions; ForgeClusterUnavailable exhausted cluster attempts; and ForgeIntegrationError optional adapters. Some invalid client arguments raise ValueError before network activity.

str(ForgeHTTPError) provides bounded, partially redacted diagnostics, but detail can still contain raw structured data. Do not assume that dumping raw details into logs is safe.

Sources and verification

This page describes the behavior at the pinned commits below. Recheck these contracts when upgrading.

• python-library/json_api_forge/options.py
• python-library/json_api_forge/client.py
• python-library/json_api_forge/errors.py
• python-library/json_api_forge/enterprise.py

---

English home · All English pages · Version maintenance