← Back to documentation

Retries and Delivery Behavior

What to expect from delivery outcomes and how to build safe retry/idempotency patterns.

6 min read

Use this guide to configure retries correctly and interpret delivery behavior.

Purpose

This guide covers:

  • Endpoint-level retry configuration.
  • Plan-based retry caps.
  • Activity outcomes tied to failed deliveries.
  • Idempotency guidance for receivers.

How retries actually work

Retries are endpoint-configured, not globally automatic.

  • deliveryRetries is set per endpoint.
  • Default is 0.
  • Effective retries are capped by your plan tier.

Plan caps:

Plan Max retries per delivery
Basic 0
Pro 3
Ultimate 5
Unlimited 5

If endpoint retries are higher than the plan cap, the API rejects the configuration.

Retry schedule uses delay buckets:

  • 30 seconds
  • 2 minutes
  • 10 minutes
  • 30 minutes
  • 1 hour

Only as many delays as needed are used (based on effective retry count).

Test deliveries are queued with maxRetries=0 and are not retried.

Prerequisites and permissions

  • Endpoint edit access.
  • Billing page access to check plan limits.
  • Activity access for monitoring outcomes.

Step-by-step workflow

1. Confirm plan retry cap

  1. Open Billing.
  2. Check Delivery retries / maxRetries for your tier.

2. Configure endpoint retries

  1. Open endpoint edit page.
  2. In Details, set Delivery retries within plan range.
  3. Save.

3. Monitor outcomes

In Request activity, monitor for:

  • DELIVERY_FAILED (delivery failed after configured retries)
  • TEST_REJECTED / TEST_RATE_LIMITED (target-test-only outcomes)

4. Make downstream handling idempotent

Receivers should tolerate repeated deliveries:

  • Deduplicate on stable event identifiers when available.
  • Make writes idempotent.
  • Avoid side effects that fail on replays.

Expected result and verification checks

  • Endpoint retry settings match plan constraints.
  • Delivery failures are visible and actionable in Activity.
  • Downstream systems process repeated deliveries safely.

Common issues and fixes

  • Retry value rejected: reduce value to plan max.
  • Frequent DELIVERY_FAILED: validate destination auth, connectivity, TLS.
  • Unexpected duplicates downstream: add idempotency controls.

Related guides

← Back to documentation