Polling a Job: Retry-After and the Final Result

A status resource for a job reports one of a small set of states, tells the client when to ask again through the Retry-After header, and, once the job ends, either points at the result with 303 See Other or describes the failure. A client that follows those signals polls no more than it needs to and always knows whether to keep waiting.

The states. Four cover most jobs: queued, running, succeeded and failed. A long job may add a progress field, such as a percentage, while it runs. Name them in the contract, because a client branches on them.

Retry-After. It holds a number of seconds, or a date. A server that knows a job typically takes two minutes can say Retry-After: 60, and lower it near the end. Without it, clients guess, and many guess one second.

Success. 303 See Other with a Location sends the client to the result with a GET. Some APIs instead return 200 with the state succeeded and a link in the body; either works if the contract says which.

Failure. The job read itself succeeds, so it returns 200, with the state failed and an error in the same format the API uses everywhere, such as a problem details object. A 500 here would wrongly say the status read broke.

Client manners. Respect Retry-After, back off if it is absent, and stop after a documented maximum time. The status resource should expire some time after the job ends, and say so.

So a status resource answers three questions on every read: is the job done, if not, when to ask again, and if so, where is the result or what went wrong.