# Jobs, errors, and retries

## Acceptance versus completion

`execution: "auto"` permits an inline 200 or a durable 202. `"async"` always
queues on OCR, classification, Locate, and extraction. Extraction currently also
queues in auto mode. Split, text operations, Review, and Summarize are inline
operations and do not accept this execution option.

A 202 includes `job_id`, required `status_url`, timestamps, and `Location` and
`Retry-After` headers. Do not treat acceptance as success, and do not POST again
to ask whether accepted work has finished. Poll with the same organization's key.
Relative URLs resolve against the deployment origin, not the current page.

Jobs progress from `queued` to `processing`, then `succeeded` or `failed`.
Polling returns 200 for both terminal states. A failed job has structured `error`
with `code`, `message`, and `retryable`; it is not restarted by further polling.
Classification's completed `result` is its full inline classification response.
OCR and Locate also return their operation's result; extraction returns plain
`data`, `provenance`, and document geometry metadata.

Use bounded polling (for example every two seconds with a five-minute application
deadline). Preserve the job ID and status URL when your polling deadline expires;
this does not cancel the server job. Persisted ready jobs are durable dispatch
intents. In Terraform-managed deployments, scheduled reconciliation is disabled
by default. When enabled, an authenticated reconciler uses the configured UTC
schedule (every five minutes by default) to repair lost queue submissions,
interrupted extraction handoffs, and callback submissions. During reconciliation,
unfinished jobs at least 24 hours
old (since creation) are marked failed with `job_deadline_exceeded` if they have
not been updated in the last two minutes and their writer lock can be acquired.
This is a processing deadline, not a 24-hour inactivity timer; it is enforced
only when reconciliation runs.
An active or orphaned writer fence prevents automatic terminalization; crashed
writer locks require operational recovery. Do not assume a client timeout means
the work was never accepted.

## Failed jobs

`error.retryable` says whether a new job for the same input may succeed. Polling
never restarts a failed job; submit a new one. The code says whether the failure
concerns the input, the account, or the service:

| Code | Concerns | Retryable |
| --- | --- | --- |
| `invalid_document` | The file could not be parsed (for example a malformed CSV) | No |
| `invalid_input` | The file or request options were rejected | No |
| `ocr_returned_no_pages` | OCR found no extractable pages | No |
| `quota_exceeded`, `organization_inactive`, `billable_ocr_disabled` | The account | No |
| `provider_not_configured` | No usable model provider credential for the organization | No |
| `upstream_model_error` | The model provider failed | Yes, unless the provider rejected the request |
| `service_unavailable`, `document_text_busy`, `catalog_unavailable` | Nugget or Google Cloud | Yes |
| `job_deadline_exceeded` | Processing did not finish within 24 hours | Yes |
| `processing_failed` | An unclassified service failure, not a verdict on the input | No |

Treat unknown codes as service failures. Workers retry transient failures through
the task queue first; a job fails with a retryable code only after the queue's
final attempt. Jobs that failed before this release report the stored code (or
`invalid_input` for an input message) in the same shape.

## HTTP errors

```json
{
  "error": {
    "code": "quota_unavailable",
    "message": "Hosted quota service is unavailable",
    "details": null,
    "retryable": true,
    "request_id": "request-id"
  }
}
```

Request validation normally returns 400, with argument locations in
`error.details.errors`. A genuine semantic/output constraint failure can return
422. Authentication failures return 401; inaccessible resources return 404.
409 indicates a real conflict, such as an idempotency mismatch, sealed upload,
nonterminal deletion, or write contention. Inspect the error code rather than
handling every 409 as OCR-busy acceptance.

For retryable failures use bounded exponential backoff with jitter, honor
`Retry-After` (seconds or HTTP date), and set an overall deadline. Error
retryability does not make every POST safe to replay. Platform-generated errors
may not use Nugget's JSON envelope; inspect status/content type before decoding.

Model discovery on a cold instance can return `503 catalog_unavailable` with
`Retry-After: 5`. Retry discovery GETs with bounded backoff. Queued classification
prepares its tenant-scoped catalog and retries transient catalog failures internally;
keep polling the accepted job rather than submitting replacement work.

## Idempotency boundaries

Review, Summarize, and queued document creation support `Idempotency-Key`.
For OCR, classification, and `/v1/locate`, explicitly set `execution: "async"`
when supplying a key; auto mode with a key returns 400. Extraction and
`/v1/locate_jobs` always queue and accept a key in either execution mode.

Choose a unique key of 1–200 visible ASCII characters per logical operation.
The key is scoped to the organization and operation, not the individual API key.
Replay the same parsed arguments and direct-upload bytes. Matching retries return
the original 202 acceptance and polling URL, even if processing has finished;
poll to get current status. Different arguments return `409 idempotency_conflict`.
An in-flight or uncertain reservation returns `409 idempotency_in_progress` with
`Retry-After`; do not switch keys just to bypass it. An orphaned reservation can
require operator recovery. A deleted/expired job with a retained acceptance
record returns `410 job_expired` instead of creating replacement work.

Default Terraform idempotency retention is one day. After a record expires, its
key can create new work: keep polling URLs durably and restrict retry windows.
Semantic caches are not request idempotency. Unkeyed POST retries can create
duplicate jobs and provider spend. Worker execution is at-least-once; idempotent
creation does not promise exactly-once external provider calls.

## Cleanup

DELETE a terminal job at its polling URL to delete its stored job resources.
Deleting a queued/processing job returns 409; this is not cancellation. Subsequent
reads and repeated deletes may return 404. Deleting a job is not a promise to
purge all independently cached document derivatives or backups. See
[Retention and deletion](/guides/retention).

A terminal job with unfinished source cleanup returns retryable
`409 job_cleanup_pending` and `Retry-After`. Retry DELETE after cleanup completes;
the job stays available to workers and reconciliation in the meantime. If it
persists, operators should check worker retries and the reconciliation configuration.
