Aevum Zenth

⚡ Quick Summary

Implement exponential backoff with full jitter, cap retries at 3 attempts, and strictly respect Retry-After headers. Never retry on 4xx errors except 429 and 408. All mutations must use idempotency keys.

Core Retry Principles

Aevum Zenth operates across a globally distributed mesh. Transient failures are expected. Your client implementations must adhere to these guidelines to prevent cascading failures and respect service quotas.

Max Attempts: 3 (initial + 2 retries)
Base Delay: 500ms
Max Delay: 10s
Jitter: Full randomization within [0, current_delay]
Timeout: 8s request timeout, 3s read timeout

HTTP Status Code Handling

Retry behavior is strictly determined by the HTTP status code returned by the endpoint. The following table defines the expected behavior:

Status Code	Description	Retry Action	Notes
2xx	Success	NO RETRY	Process response immediately
4xx	Client Error	NO RETRY	Fix request payload/headers. Exception: 408, 429, 409
429	Too Many Requests	RETRY	Mandatory: Read `Retry-After` header. Do not apply backoff formula.
500	Internal Server Error	RETRY	Transient. Apply exponential backoff.
502/503/504	Gateway/Overload	RETRY	Load balancer or upstream failure. Apply backoff.
408	Request Timeout	CAUTION	Only retry if idempotency key is provided or method is safe

Exponential Backoff Configuration

Implement backoff using the following parameters. Full jitter is required to prevent synchronization of retries across distributed clients.

base_delay

500ms

Initial wait before first retry

multiplier

2.0

Exponential growth factor

max_delay

10,000ms

Hard cap on wait time

max_attempts

Initial request + 2 retries

// Recommended backoff formula (Full Jitter)
const calculateDelay = (attempt) => {
  const base = 500;
  const max = 10000;
  const exponential = Math.min(max, base * Math.pow(2, attempt));
  return Math.random() * exponential; // Full jitter};

Idempotency & Safe Retries

Retrying non-idempotent requests can lead to duplicate transactions, double-charges, or corrupted state. Aevum Zenth enforces strict idempotency rules:

Safe Methods: GET, HEAD, OPTIONS are inherently idempotent. Safe to retry.
Unsafe Methods: POST, PUT, PATCH, DELETE require an Idempotency-Key header.
Key Format: UUID v4, case-insensitive, max 128 characters.
Keys are cached for 24 hours. Reusing a key returns the original response without reprocessing.

# cURL Example
curl -X POST https://api.aevumzenth.com/v1/payments \
  -H "Authorization: Bearer <token>" \
  -H "Idempotency-Key: a3f1b9c2-4d8e-4f1a-9b2c-7e5d6f8a0b1c" \
  -H "Content-Type: application/json" \
  -d '{"amount": 1500, "currency": "USD"}'

SDK Implementations

Official Aevum Zenth SDKs include built-in retry logic compliant with these policies. Enable it via configuration:

// JavaScript / TypeScript
import { AevumZenthClient } from '@aevumzenth/sdk-js';

const client = new AevumZenthClient({
  apiKey: process.env.AZ_API_KEY,
  retry: {
    enabled: true,
    maxAttempts: 3,
    baseDelayMs: 500,
    strategy: 'exponential_jitter' // default
  }
});

# Python
from aevumzenth import Client

client = Client(
    api_key=os.environ["AZ_API_KEY"],
    retry_config={
        "enabled": True,
        "max_retries": 3,
        "backoff_type": "exponential",
        "respect_retry_after": True
    }
)

Enterprise & Custom Policies

For high-throughput or mission-critical integrations (Enterprise Tier), Aevum Zenth supports custom retry configurations via dedicated VPC endpoints and circuit breaker patterns. Contact your solutions architect to configure:

Dedicated retry queues with at-least-once delivery guarantees
Service-specific backoff overrides
Real-time retry telemetry via X-AZ-Retry-Trace-Id
SLA-backed automatic failover to regional mirrors

⚠️ Warning: Thundering Herd Prevention

Do not implement linear backoff or retry all requests synchronously. Always randomize delay intervals. Aggressive retry patterns may trigger automatic IP throttling or rate limit bans.

Retry Policies

Core Retry Principles

HTTP Status Code Handling

Exponential Backoff Configuration

Idempotency & Safe Retries

SDK Implementations

Enterprise & Custom Policies