Rate-Limit Backoff Configuration in the Chappie SDK

When the ChatGPT/Codex backend returns an HTTP 429 Too Many Requests response, Chappie automatically retries the request with exponential backoff so your app stays responsive without hammering the API. You can tune the retry count, delay bounds, and header behaviour — or disable backoff entirely — through ChappieRateLimitBackoffPolicy.

Default behaviour

The default policy (ChappieRateLimitBackoffPolicy.default) retries up to 2 times, starting with a 1-second delay, capped at 30 seconds, and always honours the Retry-After response header when the server includes one. After all retries are exhausted, Chappie throws ChappieClientError.usageLimitReached (if the response body carries usage-limit metadata) or a ChappieClientError.httpError(429, ...) otherwise.

Policy parameters

Int

default:"2"

The maximum number of retry attempts after the first 429. Set to 0 to disable automatic retries entirely — equivalent to using .disabled. The SDK clamps negative values to 0.

TimeInterval

default:"1"

The initial wait in seconds before the first retry. Subsequent retries double this value up to maximumDelay. The SDK clamps negative values to 0.

TimeInterval

default:"30"

The upper bound in seconds for the exponential delay. No retry waits longer than this value, even if the Retry-After header requests a longer wait. The SDK clamps negative values to 0.

Bool

default:"true"

When true, Chappie reads the Retry-After response header and uses that value instead of the computed exponential delay, subject to maximumDelay. When false, Chappie always uses its own computed backoff and ignores the header.

Customising backoff

Pass a ChappieRateLimitBackoffPolicy to Chappie.client(rateLimitBackoff:) or embed it in a ChappieConfiguration:

let client = Chappie.client(
    rateLimitBackoff: ChappieRateLimitBackoffPolicy(
        maxRetries: 3,
        initialDelay: 1,
        maximumDelay: 15,
        respectsRetryAfterHeader: true
    )
)

Via a shared configuration:

let config = ChappieConfiguration(
    rateLimitBackoff: ChappieRateLimitBackoffPolicy(
        maxRetries: 3,
        initialDelay: 1,
        maximumDelay: 15,
        respectsRetryAfterHeader: true
    )
)

let authSession = Chappie.authSession(configuration: config)
let client = Chappie.client(configuration: config)

Disabling backoff entirely

Use the .disabled static value to turn off all automatic retries. Chappie surfaces the 429 immediately as an error:

let client = Chappie.client(rateLimitBackoff: .disabled)

What does .disabled expand to?

.disabled is a convenience static that sets maxRetries to 0:

public static let disabled = ChappieRateLimitBackoffPolicy(maxRetries: 0)

You can achieve the same result by passing ChappieRateLimitBackoffPolicy(maxRetries: 0) directly.

Handling exhausted retries

When Chappie runs out of retry attempts, it throws one of two errors depending on the response body:

ChappieClientError.usageLimitReached(ChappieUsageLimit) — when the backend returns structured usage-limit metadata (plan type, reset time, usage percentages). Inspect the associated ChappieUsageLimit value to show a meaningful message.
ChappieClientError.httpError(Int, String) — for bare 429 responses without usage-limit metadata.

do {
    let reply = try await client.send("Summarise this document.")
} catch ChappieClientError.usageLimitReached(let limit) {
    print(limit.plan?.displayName ?? "Unknown plan")
    if let resetsAt = limit.resetsAt {
        print("Resets at \(resetsAt.formatted(date: .abbreviated, time: .shortened))")
    }
} catch ChappieClientError.httpError(let status, let body) {
    print("HTTP \(status): \(body)")
}

Keep respectsRetryAfterHeader: true in production. The Retry-After header lets the server communicate the exact backoff it needs, which is almost always shorter than the worst-case exponential path and avoids unnecessary delay for your users.

Get Started

Authentication

Core Concepts

Guides

Configuration

Testing & Security

Rate-Limit Backoff Configuration in the Chappie SDK

Default behaviour

Policy parameters

Customising backoff

Disabling backoff entirely

Handling exhausted retries

​Default behaviour

​Policy parameters

​Customising backoff

​Disabling backoff entirely

​Handling exhausted retries

Default behaviour

Policy parameters

Customising backoff

Disabling backoff entirely

Handling exhausted retries