Guide

Prepare your integration for production launch with one hardening playbook

Use this guide when you are moving from a successful demo to real traffic. The examples move from a minimal launch-safe single-render path to a realistic retry and monitoring posture and then to a multi-workflow readiness check for teams shipping single, accepted, and batch flows together.

Launch path

Start with one launch-safe render path and bounded failure handling.
Add telemetry, retry, and quota checks for the workflow you will ship first.
Expand to accepted jobs and batch monitoring only after the core path is measurable.

Primary goal

Launch with predictable recovery paths for auth, quota, accepted-work, and backlog pressure.

Applies to

Single render, accepted job retrieval, and batch workflows with callbacks.

Guide spectrum

This page shows one easiest path, one realistic path, and one advanced path.

Before You Begin

Set ownership, release boundaries, and staging coverage first

Production hardening works best when the operating boundaries are explicit before the first traffic ramp.

Owners and rollback authority assigned

Know who can rotate keys, pause traffic, approve the release, and respond to customer-facing failures.

Staging mirrors the workflows you plan to launch

Cover single render, accepted job follow-up, batch status, and retrieval behavior before launch week.

Telemetry access is already in place

You need visibility into usage summary, request logs, and batch metrics before a go or no-go meeting can be meaningful.

Easiest Path

Launch one single-render workflow with idempotency and explicit response handling

Start with the smallest production-safe path: one render route, one environment-specific key, and one clear branch for success versus retryable failure.

Minimal launch-safe request

curl -X POST "https://api.solidrelay.io/v1/pdf" \
  -H "X-API-Key: sk_live_launchxxxxxxxxxxxx" \
  -H "Idempotency-Key: launch-smoke-001" \
  -H "Content-Type: application/json" \
  -d '{
    "html": "<h1>Launch smoke test</h1><p>invoice 1001</p>",
    "output": "url",
    "filename": "launch-smoke.pdf"
  }'

200 OK

{
  "success": true,
  "url": "https://cdn.example.com/pdfs/launch-smoke.pdf?expires=1776000000",
  "expiresAt": "2026-04-10T19:30:00.000Z",
  "metadata": {
    "size": 245789,
    "processingTime": 1840,
    "mode": "html",
    "format": "Letter"
  }
}

Minimum response posture for launch day

200 success

complete now

Return the file or signed URL to the caller and log the request outcome.

202 Accepted

store job state

Persist the returned jobId, statusUrl, and fileUrl instead of submitting a second create request.

429 or transient 5xx

retryable

Retry with the same request body and same Idempotency-Key using capped exponential backoff plus jitter.

Auth or validation 4xx

fix before retry

Stop the loop, correct credentials or payload shape, and only then send a new request.

Realistic Path

Add bounded retries, accepted-work recovery, and telemetry checks to the workflow you will actually ship

This is the normal first-production posture for teams that expect some renders to finish asynchronously and need launch signals beyond a one-time staging success.

Async create request with idempotency

curl -X POST "https://api.solidrelay.io/v1/pdf" \
  -H "X-API-Key: sk_live_launchxxxxxxxxxxxx" \
  -H "Idempotency-Key: invoice-sync-1001" \
  -H "Content-Type: application/json" \
  -d '{
    "templateId": "2a2bc604-feb7-41b5-8e2c-2e2784ecb67d",
    "data": {
      "invoiceNumber": "INV-1001",
      "customer": {
        "name": "Acme Corp",
        "region": "NA"
      },
      "lineItems": [
        { "sku": "SVC-001", "quantity": 2, "amount": "125.00" }
      ]
    },
    "output": "url",
    "executionMode": "async",
    "filename": "invoice-1001.pdf"
  }'

202 Accepted

{
  "success": true,
  "jobId": "job_01JX8V4Q8S9R6Z0ABCDE12345",
  "status": "queued",
  "statusUrl": "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345",
  "fileUrl": "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345/file"
}

Persist job identifiers before leaving the request scope

Store jobId, statusUrl, and fileUrl so follow-up work can recover from app restarts or dropped responses.

Bound retries and honor server pacing

Retry only 429 and transient 5xx responses, honor Retry-After, and stop after a finite number of attempts.

Watch usage limits and request outcomes every day of the ramp

Use usage summary to track quota headroom and use request logs to see whether accepted follow-up and file retrieval are staying healthy.

Check quota and throughput posture

curl "https://api.solidrelay.io/user/usage?period=7d&includeBreakdown=true" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "plan": "professional",
  "totalRequests": 1812,
  "successCount": 1768,
  "failedCount": 44,
  "errorsByCategory": {
    "validation": 18,
    "render": 21,
    "timeout": 5
  },
  "remaining": 7288,
  "requestsPerMinute": 120,
  "concurrentRenders": 10,
  "maxInputSizeBytes": 2000000,
  "maxOutputSizeBytes": 25000000,
  "maxTimeoutMs": 30000,
  "resetDate": "2026-04-28"
}

Confirm request-to-output behavior

curl "https://api.solidrelay.io/user/request-logs?period=1d&limit=10&sort=created_desc" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "total": 18,
  "limit": 10,
  "offset": 0,
  "summary": {
    "successCount": 17,
    "failedCount": 1
  },
  "logs": [
    {
      "id": "00000000-0000-4000-8000-000000000901",
      "apiKeyId": "00000000-0000-4000-8000-000000000111",
      "apiKeyPrefix": "sk_live_7f3a",
      "endpoint": "/v1/pdf",
      "ipAddress": "203.0.113.10",
      "status": "success",
      "errorReason": null,
      "createdAt": "2026-04-10T13:42:11.004Z"
    },
    {
      "id": "00000000-0000-4000-8000-000000000902",
      "apiKeyId": "00000000-0000-4000-8000-000000000111",
      "apiKeyPrefix": "sk_live_7f3a",
      "endpoint": "/v1/pdf/jobs/job_01JX8V4Q8S9R6Z0ABCDE12345",
      "ipAddress": "203.0.113.10",
      "status": "success",
      "errorReason": null,
      "createdAt": "2026-04-10T13:42:13.201Z"
    }
  ],
  "canRevealIp": true
}

Advanced Path

Run one go or no-go review across single render, accepted jobs, and batch callbacks

Use this path when the same launch window includes more than one workflow. The goal is to prove each surface has a known success path, a known retry boundary, and an observable failure signal before full traffic opens.

Check batch reliability before launch

curl "https://api.solidrelay.io/user/batches/metrics?period=7d" \
  -H "Authorization: Bearer ACCESS_TOKEN"

200 OK

{
  "queueDepth": 3,
  "activeBatches": 5,
  "queuedBatches": 3,
  "processingBatches": 2,
  "completionRatePercent": 94,
  "itemSuccessRatePercent": 97,
  "itemEligibleCount": 2741,
  "averageItemsPerBatch": 24.63,
  "averageBatchProcessingTimeMs": 38621,
  "webhookSuccessRatePercent": 99,
  "webhookEligibleCount": 81,
  "webhookDeliveredCount": 80,
  "commonFailureReasons": [
    { "code": "TIMEOUT", "count": 17 },
    { "code": "INVALID_URL", "count": 8 }
  ],
  "lookbackDays": 7,
  "generatedAt": "2026-04-10T13:45:24.002Z"
}

Multi-workflow readiness model

Single render lane

fast-path checked

One representative request completes successfully with the real production key, realistic payload size, and user-visible delivery behavior.

Accepted-work lane

recovery checked

The application persists the accepted envelope, follows the job route, and can still retrieve output after a restart or transient network failure.

Batch lane

callback and fallback checked

Webhook delivery is monitored, but terminal decisions still reconcile through batch status and item outcomes before any retry or download action.

Shared launch gate

usage plus failure signals

Quota headroom, request-log health, and batch metrics all stay inside the thresholds your release owner already agreed to.

Credentials

Environment-specific keys are active, validated, and rotation has been rehearsed.

Retries

Create routes use idempotency and every retry loop has a finite cap.

Accepted recovery

Operators can trace request -> job status -> file retrieval without resubmitting work.

Batch health

Webhook success rate, batch completion rate, and common failure reasons are reviewed before the traffic ramp.

Keep the deep implementation details in the workflow guides:accepted render flow for polling and retrieval, andbatch with webhooks for callback verification and reconciliation.

Launch Blockers

Stop the rollout when these signals appear

Environment keys are shared or cannot be rotated cleanly.
Create routes can retry, but the client does not persist Idempotency-Key or accepted job identifiers.
Usage summary shows low remaining quota, no alert coverage for request pressure, or no agreed response to sustained 429.
Request logs cannot trace the workflow from create to retrieval well enough to debug a real customer incident.
Batch launches depend only on webhook completion without status reconciliation or item-level review.

Next Steps

Use canonical workflow guides and references to keep the launch posture current

Guide

Retries and idempotency

Standardize retry policy for create routes before you scale traffic.

Guide

Key rotation

Keep credential cutover, validation, and compromise response aligned with your launch plan.

Guide

Reference

Single render reference

Confirm request, output, and accepted-response details for POST /v1/pdf.

Reference

Usage and limits reference

Use usage summary, request logs, and batch metrics to keep launch assumptions honest.

Reference