Skip to content

Report a failed job

POST
/jobs/{id}/fail

Records that a job you hold has failed and releases your claim. With terminal: true the job becomes failed and the server won’t retry it.

Otherwise it goes back to pending and can be claimed again right away, unless it has used all its attempts, in which case it becomes failed too. An administrator can still put a failed job back on the queue, which resets its attempts.

Send the worker_id you claimed with. You get 409 if the job isn’t running under that worker_id, which also covers an unknown id, and 401 if worker_id is missing or empty. Any signed-in account can make this call: worker_id is just the label stored with the claim, not proof that you made it.

There’s no delay before a retry, and reporting a failure doesn’t stop work that is still running anywhere.

id
required
string format: uuid

The job’s id, from POST /jobs/claim.

object
worker_id
required

The worker_id you claimed the job with.

string
>= 1 characters <= 200 characters
error
required

What went wrong, stored as the job’s last_error. It isn’t checked, so a missing value is stored as an empty string.

string
terminal

true if trying again won’t help. Defaults to false.

boolean

The failure was recorded.

Authentication required, missing, or invalid

object
error
required

Human-readable error summary

string
Example
the request could not be completed
Example
{
"error": "authentication required: sign in and retry with a valid session or API token"
}

The job isn’t running under this worker_id, or doesn’t exist.