Retry create requests safely without duplicating render work

• Generate the key before attempt one. Do not generate a new key after a timeout.
• Persist key and request body together so process restarts can replay safely.
• Use the same key only for retries of the same logical create request body.
• Use a new key whenever meaningful request input changes.
• Set a max retry budget and backoff strategy up front so failures do not produce unbounded loops.

For the shared mental model, read the idempotency concept page. Use this guide for route-specific implementation order.

Easiest path

Start with one small single render. If the client loses the first response, retry the exact same request with the exact same key.

curl -X POST "https://api.solidrelay.io/v1/pdf" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: receipt-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Receipt 1001</h1>",
    "output": "binary",
    "executionMode": "sync"
  }'

curl -X POST "https://api.solidrelay.io/v1/pdf" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: receipt-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Receipt 1001</h1>",
    "output": "binary",
    "executionMode": "sync"
  }'

HTTP/1.1 202 Accepted
{
  "success": true,
  "jobId": "7b6f4c93-34e3-4f6d-a32d-9a2f0b2054d1",
  "status": "queued",
  "statusUrl": "/v1/pdf/jobs/7b6f4c93-34e3-4f6d-a32d-9a2f0b2054d1",
  "fileUrl": "/v1/pdf/jobs/7b6f4c93-34e3-4f6d-a32d-9a2f0b2054d1/file"
}

• The second create uses the same key and the same body because it is the same logical operation.
• If the replay returns 202 Accepted, store jobId, statusUrl, and fileUrl, then move to follow-up handling.

Realistic path

This is the version most teams should implement first for batch create: deterministic item IDs, one idempotency key for the whole request, and explicit acceptance handling.

curl -X POST "https://api.solidrelay.io/v1/pdf/batch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: batch-invoices-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "invoice_001", "html": "<h1>Invoice 1</h1>" },
      { "id": "invoice_002", "html": "<h1>Invoice 2</h1>" }
    ]
  }'

HTTP/1.1 202 Accepted
{
  "jobId": "4f93c86f-3b9f-4bd8-9f8e-bba2f8dd760d",
  "status": "queued",
  "itemCount": 2,
  "totalCount": 2,
  "statusUrl": "/v1/pdf/batch/4f93c86f-3b9f-4bd8-9f8e-bba2f8dd760d",
  "estimatedCompletionTime": "2026-04-10T15:13:00.000Z",
  "expiresAt": "2026-04-11T15:10:00.000Z"
}

• Use deterministic item IDs so retries, reconciliation, and downstream bookkeeping stay stable.
• For batch create, acceptance means the job exists. Continue on the batch status route instead of resending changed work under the same key.

Advanced path

This is where retry loops need multiple decisions: accepted follow-up for single render, short-delay retries for in-flight batch keys, and a hard stop when the request body changes.

curl "https://api.solidrelay.io/v1/pdf/jobs/7b6f4c93-34e3-4f6d-a32d-9a2f0b2054d1" \
  -H "X-API-Key: YOUR_API_KEY"

{
  "success": true,
  "jobId": "7b6f4c93-34e3-4f6d-a32d-9a2f0b2054d1",
  "status": "queued",
  "inputMode": "html",
  "outputMode": "binary",
  "createdAt": "2026-04-10T15:00:00.000Z",
  "updatedAt": "2026-04-10T15:00:18.000Z",
  "completedAt": null,
  "outputAvailable": false,
  "outputExpiresAt": null,
  "downloadUrlEndpoint": "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345/download-url",
  "fileName": "document.pdf",
  "pdfSize": 0,
  "pages": 0,
  "processingTimeMs": 0,
  "attemptCount": 2,
  "retryAttempt": 2,
  "maxAttempts": 5,
  "willRetry": true,
  "deadLettered": false,
  "error": {
    "code": "RETRY_SCHEDULED",
    "message": "Transient render failure. Retry scheduled (attempt 2 of 5)."
  }
}

HTTP/1.1 409 Conflict
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Idempotency key is currently being processed. Retry with the same key shortly."
}

curl -X POST "https://api.solidrelay.io/v1/pdf/batch" \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Idempotency-Key: batch-invoices-2026-04-01" \
  -H "Content-Type: application/json" \
  -d '{
    "items": [
      { "id": "invoice_001", "html": "<h1>Invoice 1 - corrected</h1>" },
      { "id": "invoice_002", "html": "<h1>Invoice 2</h1>" }
    ]
  }'

HTTP/1.1 409 Conflict
{
  "statusCode": 409,
  "error": "Conflict",
  "message": "Idempotency key has already been used with a different batch request"
}

• willRetry: true on accepted job status means keep following that job, not the original create loop.
• The batch message "currently being processed" is the one 409 case that still wants a short-delay retry with the same key and same body.
• A changed-body conflict is a hard stop. Generate a new key only when you intentionally submit new work.

• Use capped exponential backoff with jitter for retryable failures to avoid synchronized retry spikes.
• Treat changed-payload conflict as non-retryable; generate a new key only when sending new work on purpose.
• Treat the batch response "Idempotency key is currently being processed" as retryable with a short delay and unchanged request.
• Do not rotate keys between attempts of the same logical create request.
• Log idempotency key, request hash, status code, and correlation IDs to simplify incident debugging.

Reference pages: single render and batch rendering. Use the errors page as the shared retryability contract for rate limits, transient server failures, and non-retryable client responses.