> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gavai.io/llms.txt
> Use this file to discover all available pages before exploring further.
# Retry behavior and circuit breaker
> The exact retry schedule, what counts as failure, and how to recover from an open breaker.
export const ErrorTable = ({errors}) =>
;
export const Eyebrow = ({label, tone = "default"}) =>
{label}
;
When your endpoint doesn't respond `2xx` within 10 seconds, the gavAI dispatcher retries the delivery on a fixed exponential schedule. After enough consecutive deliveries have exhausted all their retries, a circuit breaker opens and pauses traffic to that endpoint for an hour. This page is the spec for both behaviors — the exact schedule, what counts as failure, and what to do when the breaker trips. By the end you'll know how long you have to recover from an outage before deliveries start getting dropped.
## A delivery's lifecycle
```mermaid theme={null}
stateDiagram-v2
[*] --> Pending
Pending --> Delivered: 2xx within 10 s
Pending --> Retrying: non-2xx, timeout, or connection error
Retrying --> Pending: backoff delay elapses (attempts < 6)
Retrying --> Exhausted: 6 attempts failed
Delivered --> [*]
Exhausted --> [*]
```
A single delivery (`whd_01H...`) walks this graph. Each transition through `Pending → Retrying → Pending` is one retry attempt, and the dispatcher gives up after the sixth attempt fails. Exhausted deliveries are recorded in the delivery log but not re-attempted automatically — you can replay them from the console for up to 7 days.
## The retry schedule
A single event gets up to 6 delivery attempts. The delay before each attempt is fixed:
End to end, a single delivery has roughly 1 hour 6 minutes from initial dispatch to the final attempt. That's your maximum recovery window for a transient outage. Anything longer and the dispatcher gives up on that specific delivery — though new events keep flowing, see the circuit breaker below.
## What counts as a delivery failure
The dispatcher treats any of these as a failed attempt and schedules the next retry:
A `2xx` is the only thing that closes the delivery successfully — including `204 No Content` and `202 Accepted`. Return whatever 2xx is most truthful for your handler.
## The circuit breaker
Six attempts on a single event is one kind of failure. A persistently broken endpoint is a different kind, and the dispatcher handles it separately so one bad endpoint can't burn the retry queue for the whole workspace.
After **5 consecutive deliveries each exhaust all 6 attempts** (5 × 6 = 30 total failed attempts) on the same subscription, the circuit breaker opens. While it's open:
**No events are delivered** to that endpoint. The dispatcher records the events but does not attempt to push them.**Events that fire during this window are dropped, not queued.** This is the most important sentence on this page. If your application can't tolerate gaps, the recovery story is reconciliation via the [Audit log API](/api-reference/resources/logs), not waiting for the dispatcher to replay them.**The breaker resets automatically after 1 hour.** No manual action needed for the reset itself.
The 1-hour cool-down is deliberate — it gives a deploy or cert renewal time to land without you having to chase a button to re-enable the subscription.
## Recovering from an open breaker
Look at the delivery log at `GET /v1/workspaces/acme/webhook-deliveries` (or the **Deliveries** tab in the console). Each failed attempt records the response status, the first 256 bytes of the response body, and the error class. The most common causes are TLS expiry, a deploy that broke the handler, and a missing raw-body reader after a framework upgrade. Verify your endpoint returns `2xx` to a manual `curl` before doing anything else.
The breaker resets on its own after 1 hour. To verify the fix without waiting, fire a test event from `/console/settings/webhooks → your subscription → Send test event` once the cool-down is past. Test events bypass the breaker only after it has reset.
The first successful `2xx` delivery after the breaker resets closes it. Normal traffic resumes immediately.
Events that fired while the breaker was open are not replayed. If your application's correctness depends on having seen every event, query the [Audit log API](/api-reference/resources/logs) for events between the first failed delivery and the recovery moment, and process them as if they had arrived via webhook.
Dropped-during-breaker events are gone from the delivery pipeline. The audit log keeps them, but you have to ask for them — there is no automatic replay. Decide ahead of time whether your handler is the kind that needs reconciliation, and write the reconciliation script before you need it at 2 a.m.
## Operating the endpoint
**Synthetic checks beat alerts.** A health check that fires every minute against your webhook endpoint catches a TLS expiry or a bad deploy before the dispatcher does. Hook it to your pager.**Alert at 2–3 consecutive failures, not at the breaker.** The delivery log exposes per-attempt status. Alerting at the breaker means you find out 30 attempts and an hour late.**Run a test event after every deploy.** The console's Send test event button is the cheapest possible post-deploy check — fire it before real traffic hits the new version.**Respond fast, queue the work.** A handler that returns `200` in 50 ms and writes to a background queue will never hit the timeout. A handler that does the full work inline will, the first time the database has a slow afternoon.
## Where to next
Retries mean duplicates. Here's the dedupe pattern that handles them.
Build a handler from scratch — register, verify, dedupe, and test.