HTTP Status 202 - how to provide information about async request completion?

Question

What is the appropriate way of giving an estimate for request completion when the server returns a 202 - Accepted status code for asynchronous requests?

From the HTTP spec (italics added by me):

202 Accepted

The request has been accepted for processing, but the processing has not been 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.

Here are some of thoughts:

• I have glanced at the max-age directive, but using it would be abusing Cache-Control?
• Return the expected wait time in the response body?
• Add an application specific X- response header, but the X-headers was deprecated in RFC 6648?
• Add a (non X-) specific response header? If so, how should it be named? The SO question Custom HTTP headers : naming conventions gave some ideas, but after the deprecation it only answers how HTTP headers are formatted, not how they should be named.
• Other suggestions?

Answer 1

Definitely do not abuse existing HTTP headers for this. Since it's your own server, you get to define what the response looks like. You can (and should) pick whatever response works best for the intended recipient of this information and return the actual information in the response body.

For example, if you are only interested in displaying a human-readable message then you could return text/plain saying "Your request is likely to be processed in the next 30 minutes.".

At the other end of the spectrum, you might want to go all the REST way and return application/json, perhaps formatted like this (I totally made this up on the spot):

{
  "status": "pending",
  "completion": {
    "estimate": "Thu Sep 08 2011 12:00:00 GMT-0400",
    "rejected-after": "Fri Sep 09 2011 12:00:00 GMT-0400",
  },
  "tracking": {
    "url": "http://server/status?id=myUniqueId"
  }
}

Answer 2

You can use the Location header to specify the URL of the status monitor. Things like current status and estimate can either go in custom headers (which noone but your own software would use), or in the response body (which a web browser would display to a user, at least).

Answer 3

Although not explicitly mentioned specifically for the 202 - Accepted response code, the Retry-After header seems to be a suitable option. From the documentation:

The Retry-After response-header field can be used [...] to indicate how long the service is expected to be unavailable to the requesting client.