Polling Background Jobs

Some Literal operations are accepted immediately but complete asynchronously. When that happens, the API returns 202 Accepted and a Location header for the job status resource.

Overview

Some operations are accepted immediately but complete asynchronously. When that happens, Literal returns 202 Accepted and a Location header for the job status resource.

Do not treat 202 Accepted as completion. Poll the job until it reaches a terminal state.

Endpoint sequence:

• Job-creating endpoints return 202 Accepted with a Location header.
• GET /v1/jobs/{jobId} returns the current job status.

Use the API Reference for exact response fields, status codes, and errors.

Job Statuses

Only completed and failed are terminal states. Stop polling when you reach either one.

Polling With Backoff

Use bounded exponential backoff:

1. Start after 2 seconds.
2. Double the delay while the job is queued or processing.
3. Cap polling at 30 seconds between attempts.
4. Stop after a maximum age, such as 10 minutes, unless the workflow requires a longer timeout.
5. Stop immediately on terminal states.

delay = 2s

while job is not terminal:
    wait delay
    job = poll(job_url)
    delay = min(delay * 2, 30s)

Terminal States

Completed

The job finished successfully. Stop polling and verify the workflow-specific result, such as searchability after reindexing.

Failed

The job did not complete. Inspect the error returned by the job status response and decide whether to retry the original operation. Do not keep polling a failed job.

Job Expiry

Completed jobs remain queryable for 24 hours. After that, the job record expires and polling returns not found.

Do not treat every 404 as success. A 404 immediately after creating a job is unexpected; a 404 for an old job may simply mean the record expired.

Authentication

Job polling requires an authenticated session. If the access token expires while polling, refresh the session and continue polling the same job.

Example Uses

Jobs are currently used for reindex operations. After submitting a reindex request, poll the returned job URL until completion, then verify the document is searchable in the target scope.

Troubleshooting

• If a 202 response has no Location header, the job cannot be polled and the original operation should be retried.
• If polling returns 404 immediately after creating a job, treat it as an unexpected error rather than completion.
• If polling returns 429, increase the backoff before retrying.
• If a job has not reached a terminal state within the maximum age, stop polling and surface the timeout to the workflow.
• If a job ends in failed, do not re-poll the same job ID — submit a fresh operation if retry is appropriate.

See Error Handling and the API Reference for status-specific responses.

Related Resources

• Searching Over Encrypted Documents — verify searchability after indexing.
• Document Lifecycle — understand document processing states tracked outside the jobs endpoint.
• API Conventions — shared response and error behavior.
• API Reference — exact job endpoint schemas.

Last updated on