Most appropriate HTTP status code for "job in progress"

Question

What is the most appropriate HTTP status code to give to a client to mean "your request is fine, but it is still in progress; check back shortly in the exact same place."

For example, say the client submits an initial request to start a heavy query, and the server immediately returns a URL that the client can poll periodically for the result. In the case the client calls this URL before the job is completed, what is the most appropriate HTTP status code to return?

202 Accepted would be my first impulse. Is this the best one, or is there a better one that is more idiomatic for this purpose in REST interfaces?

Hau

Answer 1

To me, 202 Accepted would be the best way to go.

See the documentation on the W3C website.

10.2.3 202 Accepted

The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.

The 202 response is intentionally non-committal. Its purpose is to allow a server to accept a request for some other process (perhaps a batch-oriented process that is only run once per day) without requiring that the user agent's connection to the server persist until the process is completed. The entity returned with this response SHOULD include an indication of the request's current status and either a pointer to a status monitor or some estimate of when the user can expect the request to be fulfilled.

Annihilator

Answer 2

I'm currently working on a similar problem. I have an API that looks like this:

POST /jobs               # Creates a job
GET /jobs/{jobId}        # Gets a job
GET /jobs/{jobId}/output # Gets job output

My API flow looks like this:

POST /jobs               -> 202 Accepted, Link header to created object
GET /jobs/{jobId}        -> 200 OK, includes status field
GET /jobs/{jobId}/output -> 200 OK if job completed successfully, XXX otherwise?

So POST /jobs returns 202 when creating the job, users poll GET /jobs/{jobId} to check status, and use /jobs/{jobId}/output to get the results. Here is where I'm landing:

• If the job completed with success, then 200 OK, as shown above
• If the job completed with failure, then 409 Conflict
• If the job is processing, then either 204 No Content or 425 Too Early, depending on if I decide not polling GET /jobs/{jobId} and waiting is valid user behavior or a client error, respectively. I know 425 is technically a protocol-level error, but it's looks like the closest thing to me.

I like HATEOAS as a design concept, but it feels like we're missing either some important HTTP codes, guidance, or both before it's fully useable.

Clamper