Retry API v1

x402 quickstart

Send an unauthenticated creation request. The first response is HTTP 402 with aPAYMENT-REQUIRED header that advertises x402 v2, exact settlement, 20,000 atomic USDC units, and Baseeip155:8453. Use the returned requirements rather than hardcoding the recipient.

curl -i -X POST \
  https://retry.exende.dev/v1/retries \
  -H "Content-Type: application/json" \
  --data '{
    "request": {
      "method": "GET",
      "url": "https://httpbin.org/status/204"
    },
    "retry": {
      "max_attempts": 8,
      "strategy": "exponential",
      "initial_delay_seconds": 5,
      "max_delay_seconds": 300
    }
  }'

{
  "id": "retry_0123456789abcdef0123456789abcdef",
  "status": "pending",
  "attempts": 0,
  "max_attempts": 8,
  "created_at": "2026-08-24T12:00:00.000Z",
  "next_attempt_at": "2026-08-24T12:00:00.000Z",
  "status_url": "https://retry.exende.dev/v1/retries/retry_0123456789abcdef0123456789abcdef",
  "read_token": "ex_retry_read_..."
}

Create a Retry job

POST https://retry.exende.dev/v1/retries

If the outbound body is JSON, set Content-Type inside request.headers. Exende serializes the value but does not infer the upstream content type. success_codes and retry_status_codes cannot overlap.

curl --fail-with-body -sS \
  -X POST 'https://retry.exende.dev/v1/retries' \
  -H "Authorization: Bearer $EXENDE_API_KEY" \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: refresh-customer-42-v1' \
  --data '{
    "request": {
      "method": "POST",
      "url": "https://api.example.com/customers/42/refresh",
      "headers": {"Content-Type":"application/json"},
      "body": {"source":"agent"}
    },
    "retry": {
      "max_attempts": 5,
      "strategy": "exponential",
      "initial_delay_seconds": 5,
      "max_delay_seconds": 120
    },
    "retry_status_codes": [408,425,429,500,502,503,504],
    "callback_url": "https://agent.example.com/events/exende",
    "callback_secret": "client-generated-secret-at-least-32-characters"
  }'

Job lifecycle and status

GET /v1/retries/{id}

Authenticate with the same account API key or the matching paid-job read token.

curl --fail-with-body -sS \
  'https://retry.exende.dev/v1/retries/retry_0123456789abcdef0123456789abcdef' \
  -H "Authorization: Bearer ex_retry_read_..."

{
  "id": "retry_0123456789abcdef0123456789abcdef",
  "status": "retrying",
  "request": {"method":"POST","destination_host":"api.example.com"},
  "attempts": 1,
  "max_attempts": 5,
  "generation": 1,
  "retry": {
    "strategy": "exponential",
    "initial_delay_seconds": 5,
    "max_delay_seconds": 120
  },
  "last_status_code": 503,
  "last_error_code": null,
  "created_at": "2026-08-24T12:00:00.000Z",
  "updated_at": "2026-08-24T12:00:01.000Z",
  "next_attempt_at": "2026-08-24T12:00:06.000Z",
  "completed_at": null,
  "expires_at": "2026-08-25T12:00:00.000Z",
  "attempts_url": "https://retry.exende.dev/v1/retries/retry_0123456789abcdef0123456789abcdef/attempts"
}

generation is monotonic concurrency metadata. Clients should make workflow decisions from status and timestamps rather than generation.

Attempts and history

GET /v1/retries/{id}/attempts

Attempt outcomes are success, http_failure, timeout, network_error, blocked_redirect, or cancelled. Entries include timing, status/error metadata, and the scheduled delay without persisting upstream response bodies.

{
  "retry_id": "retry_0123456789abcdef0123456789abcdef",
  "count": 2,
  "attempts": [
    {
      "attempt_number": 1,
      "outcome": "http_failure",
      "status_code": 503,
      "error_code": null,
      "duration_ms": 241,
      "retry_scheduled": true,
      "retry_delay_seconds": 5,
      "retry_after_seconds": null,
      "created_at": "2026-08-24T12:00:01.000Z"
    },
    {
      "attempt_number": 2,
      "outcome": "success",
      "status_code": 204,
      "error_code": null,
      "duration_ms": 198,
      "retry_scheduled": false,
      "retry_delay_seconds": null,
      "retry_after_seconds": null,
      "created_at": "2026-08-24T12:00:07.000Z"
    }
  ]
}

Optional terminal callback

Configure callback_url and callback_secret at creation. Retry schedules one independent delivery workflow for retry.succeeded, retry.failed, or retry.cancelled. Expired jobs do not emit a callback in v1.

Content-Type: application/json
X-Exende-Event: retry.succeeded
X-Exende-Delivery: <stable-delivery-id>
X-Exende-Timestamp: <unix-seconds>
X-Exende-Signature: <hmac-sha256-signature>

{
  "event": "retry.succeeded",
  "retry_id": "retry_0123456789abcdef0123456789abcdef",
  "status": "succeeded",
  "attempts": 2,
  "max_attempts": 5,
  "last_status_code": 204,
  "last_error_code": null,
  "completed_at": "2026-08-24T12:02:00.000Z"
}

Delivery is at-least-once. Any 2xx response succeeds. Network errors, timeouts, and 408, 425, 429, 500, 502, 503, or 504 are retried up to 8 times within 24 hours. Retries keep the same X-Exende-Delivery value and use a fresh timestamp and signature. Verify HMAC against the exact raw body and deduplicate only after your business operation succeeds.

GET /v1/retries/{id}/callback

This protected endpoint returns safe delivery metadata only. It never exposes callback_url, callback_secret, raw payload, lease data, or internal generation.

Retry policies and idempotency

Retry behavior

Default retryable statuses are 408, 425, 429, 500, 502, 503, and 504. Timeouts and network errors are retryable. Attempt one runs immediately. Fixed delay starts at the configured initial delay; exponential delay doubles by attempt, is capped by max_delay_seconds, and is jittered. A valid Retry-After is a minimum delay capped by the configured maximum.

API-key idempotency

Idempotency-Key is optional, 1–255 characters, scoped to account plus key, and retained for 24 hours. An equivalent replay returns the original 201 response with Idempotency-Replayed: true; a different request returns 409 IDEMPOTENCY_KEY_CONFLICT.

x402 replay safety

Paid clients must include the x402 v2 payment-identifier extension. Reuse one identifier only for retries of the same logical paid creation. Exende binds it to the endpoint, payment requirements, and full request. This prevents duplicate Exende jobs but does not make a non-idempotent upstream operation exactly-once.

API-key-only operations

Paid x402 jobs are covered by the fixed job price and do not appear as API-key billable attempts. A paid-job read token cannot cancel a job or read aggregate usage.

Errors, security, and limits

Clients should branch on error.code rather than message. Retry accepts public HTTPS destinations only, blocks IP literals and private/internal/Exende hosts, revalidates up to three same-origin redirects, and applies a 20-second timeout across the complete chain.

{
  "error": {
    "code": "INVALID_REQUEST",
    "message": "Human-readable explanation."
  }
}

Production limits

OpenAPI and Bazaar discovery

The static OpenAPI 3.1 specification describes both creation paths and every public Retry endpoint. The paid POST resource is also currently discoverable through Coinbase x402 Bazaar with the exact $0.02 Base USDC requirement.