Handling errors & retries

Every event that fails a transform or a destination write is retried automatically. This guide covers how that works and what to do when retries run out.

Automatic retries

Failed events retry with exponential backoff — 1s, 2s, 4s, up to a per-pipeline configurable ceiling. Most transient failures (a destination hiccup, a rate-limited third party) resolve within the first few attempts.

{
  "retry_policy": {
    "max_attempts": 5,
    "backoff": "exponential",
    "initial_delay_ms": 1000
  }
}

Dead-lettering

An event that exhausts its retries is moved to that pipeline's dead-letter queue rather than dropped silently.

Dead-lettered events don't retry themselves

Once in the dead-letter queue, an event stays there until you replay it or explicitly discard it — it will not retry again on its own.

Replaying events

Use the Events endpoint's replay action to re-run a specific dead-lettered event once the underlying issue is fixed.

curl -X POST https://api.kmp.kaiju.go.example/v2/events/evt_8f2c1a90/replay \
  -H "Authorization: Bearer $KMP_API_KEY"

Watching for failures

Subscribe to pipeline.failed via Webhooks so you find out about dead-lettered events before a customer does. See also Monitoring & alerts.