NuggetAPI referenceAPI consoleOpenAPI

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.