Errors, idempotency, and retries

Keep the HTTP status and the server’s error body. The error code is useful for application handling; the message provides context. Do not assume every non-2xx response is JSON: gateways can return text errors.

Response	Typical handling
`400`	Correct the request or unsupported options.
`401`, `403`	Check credentials and permissions.
`404`, `410`	Check the ID and whether content expired or was deleted.
`409`	Inspect the code: idempotency conflict, claimed input, or pinned content may require different actions.
`429`, `502`, `503`, `504`	Consider a bounded retry where the operation is safe to replay. Honor `Retry-After`.

See each endpoint’s response schema for its documented errors.

Idempotency

Send Idempotency-Key on uploads, prompt/conversion creation, webhook creation, and manual webhook-delivery retry. Repeating the same operation with the same key and body can replay it; changing the body returns a conflict. Response header Idempotent-Replayed: true identifies a replay. Use nonempty printable ASCII keys without spaces. Ordinary creation keys allow up to 200 characters; webhook creation/retry keys allow 128. Keep upload and job keys distinct. New encryption public keys change the request body and therefore need a new operation key. Do not blindly retry cancel/resume actions or generate a fresh key after an ambiguous submission failure. If you know the job ID, retrieve that job. If the submission response was lost, replay the identical request with its original key. A failed download is not a reason to create another paid job.

TypeScript recovery

import { ReviseClient, Source, ReviseWorkflowError } from "@reviseio/api";

const revise = new ReviseClient({ apiKey: process.env.REVISE_API_KEY! });
try {
  const pdf = await revise.convert(
    Source.fromText("# Report", { filename: "report.md" }),
    "pdf",
    { idempotencyKey: "report-42", timeoutMs: 120_000 },
  );
  const bytes = await pdf.bytes({ signal: AbortSignal.timeout(60_000) });
} catch (error) {
  if (error instanceof ReviseWorkflowError) {
    console.error(error.recovery.jobId, error.recovery.stage);
    // Persist recovery securely to resume this operation.
  }
  throw error;
}

Helpers derive :upload and :prompt/:convert keys from a base of at most 192 characters. onProgress provides keys, IDs, and the latest receipt synchronously; it cannot await durable storage. Use low-level methods when persistence must complete between network steps. The client retries HTTP 429/502/503/504 on GET, DELETE, and supported keyed POST calls, with two additional attempts by default. It honors Retry-After and caps the delay at 60 seconds; longer advice is surfaced rather than retried early. Transport exceptions and body-read failures are not automatically retried. ReviseWorkflowError preserves recovery plus its cause. ReviseApiError exposes status, code, body, and headers; ReviseArtifactError describes integrity failures; SourceError describes source resolution failures. Lazy output reads happen after the workflow: retain the returned Source and its receipt to retry reading without resubmitting.

Getting started

Guides

REST reference

Idempotency

TypeScript recovery

​Idempotency

​TypeScript recovery

Idempotency

TypeScript recovery