Read Compute states and reason codes
What each job, batch, file and result state means, how it differs from a reason code, and what to do next.
Start with the object that returned the value, then use its state or reason table. Job, batch, artifact, delivery, event, and cancellation values answer different questions. Keep their spelling and case unchanged.
These values help your agent preserve identity, recovery and declared outcome boundaries. A state, digest or receipt does not by itself establish semantic correctness or the final acceptance decision.
Job and batch response states
GET /v1/jobs/{id} returns a job projection inside the HTTP success envelope's data. Its fields are job_id, state, state_version, digest and p_next_action.
| Field | Schema rule | How to use it |
|---|---|---|
state | Required string, 1–64 characters | Preserve the returned value. The projection schema does not declare a closed job-state enum. |
state_version | Required integer, at least 1 | Keep the version alongside the observation instead of comparing state names alphabetically. |
p_next_action | Required string, 1–256 characters | Interpret it through your application's allowed recovery actions. It is not executable code. |
digest | Required lowercase SHA-256 digest | Preserve it with the response you observed. |
GET /v1/batches/{id} returns batch_id, state, total_count, accepted_count, failed_count, digest and p_next_action. Its state is also a 1–64-character string, not the artifact or delivery enum. Each count is an integer from 0 through 1,000,000.
Do not substitute an uppercase list from another contract for these response fields. An unfamiliar job state must not become success by default. Preserve the response, retain the existing job handle, and check its result or next action before starting replacement work.
A successful status request proves that you received a status response. It does not prove that execution, result verification, delivery or payment completed.
Artifact states
ArtifactProjection.state has exactly these lowercase values. This is the artifact projection returned by artifact completion, not a universal list for every storage or workflow object.
| Value | What to distinguish |
|---|---|
prepared | Artifact preparation is distinct from uploaded bytes. |
uploaded | Upload state alone does not establish job execution or delivery. |
complete | Artifact completion is not completion of the job that uses it. |
delivered | Artifact delivery is distinct from payment. |
expired | Recheck access or transfer authority; do not keep replaying expired authorization. |
The projection also requires artifact_id, ciphertext_bytes, chunk_count and digest. A list of allowed states does not promise that every artifact visits every value in that order.
Result delivery states
GET /v1/jobs/{id}/result returns a ResultProjection. It requires job_id, encrypted_artifact_id, result_digest, evidence_digest and delivery_state.
delivery_state | First action |
|---|---|
pending | Retain the existing job and artifact references; check delivery again. |
delivering | Continue observing the same delivery rather than resubmitting the job. |
delivered | Retrieve the result through your authorized result flow and verify the expected bytes. |
failed | Investigate delivery for the existing result before considering any new Compute run. |
These four values are case-sensitive: DELIVERED is not delivered. A delivery failure does not, by itself, say that inference failed or that you should pay to run it again.
Event and cancellation reasons
EventItem requires event_id, state and digest. Its optional reason_code and timing_bucket are omitted when absent; neither schema permits null as their value. The event state is a 1–64-character string. It is not a separate declared stage-state enum.
The cancellation request and event reason field use the same seven lowercase reason codes:
| Code | Meaning to preserve in handling |
|---|---|
validation_failed | Input or output validation failed. |
verification_failed | Verification failed. |
cancelled | The reason records cancellation. |
deadline_exceeded | The deadline was exceeded. |
execution_failed | Execution failed. |
delivery_failed | Delivery failed. |
policy_refusal | Policy refused the work. |
A reason is not the current job state. Sending reason_code: "cancelled" does not prove the job has stopped. Read the cancellation response and then the existing job. Do not translate reason codes to uppercase or collapse validation, execution, and delivery failures into one retry branch.
Quote and error responses
A quote response has status: "signed" and a quote object. A signed quote is not execution approval or a completed job. Preserve its expiry and bind any submission to the approved request.
HTTP errors use ok: false, an error object and p_next_action; their error codes are not the lowercase reason-code enum above. Handle errors using the operation's error contract, not by treating any failed HTTP request as a failed job.
Use the work API reference to select the exact response schema for the operation you call.