Retries and rate limits¶

The default policy is conservative.

Default retry scope¶

GET and HEAD requests are eligible for retries. Retried conditions include transport errors and HTTP 429, 500, 502, 503, and 504.

The policy permits three attempts with exponential delay and jitter.

Write operations¶

A timeout on a create request is ambiguous. The server may commit the object without delivering a response. Without an idempotency key, replays can create duplicates.

For write operations, apply business reconciliation:

assign a client-visible marker;
execute the write;
query for success if the outcome is ambiguous;
retry only if replay is verified safe.

Project keys function as reconciliation signals when a uniqueness validation error occurs.

Custom policy¶

$policy = new RetryPolicy(
    maxAttempts: 4,
    baseDelayMs: 250,
    maxDelayMs: 5000,
    methods: ['GET'],
    statusCodes: [429, 502, 503, 504],
    retryTransportErrors: true,
    jitter: true,
);

Configure methods based on operation semantics. Do not add POST or PATCH simply to suppress errors.

External retry managers¶

If an external system owns retries, disable SDK retries to prevent multiplicative requests:

retryPolicy: RetryPolicy::disabled()