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
{
"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.
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.