# Error handling and retries

[HTML](https://pdfcraft.ai/en/docs/api/error-handling/) · [Site index](https://pdfcraft.ai/llms.txt)

Build a predictable integration when conversion tasks fail or take longer than expected.


Treat a conversion result as a stateful job, not as a synchronous file download. This keeps your product reliable when source files are large, unavailable, or malformed.

## Retry safely

Retry only requests that are safe to repeat. A result request can be retried with exponential backoff. For submit requests, persist the task ID returned by a successful response before attempting another submission.

## Handle terminal failures

When a task is `failed`, log its task ID and returned reason together with your internal job ID. Show users an actionable next step, such as checking the source URL or uploading a readable PDF, rather than exposing an unformatted API error.

## Set practical time limits

Use a polling deadline that matches your product experience. Stop polling at that deadline, retain the task ID, and let a background worker or a user-initiated refresh check the final status later.

For exact response fields and failure examples, see the [API Reference](https://pdfcraft.ai/en/api/).

## Rate limits

A 429 can mean rate, quota or concurrency exhaustion. Honor `Retry-After` when present; otherwise, use bounded exponential backoff with a deadline. Inspect the JSON error and its optional reason and retryAfterMs fields. Do not assume fixed quotas or that waiting guarantees restored capacity.

Never automatically resubmit after an ambiguous network failure. The internal request ID used by the limiter is not a documented client idempotency key. Do not assume result polling consumes the same quota as submission.