Question

I currently develop a task queue with a RESTful API.

In order to handle a task, a worker has to create a lease.

PUT .../leases

If the task queue has tasks available, this will succeed, a lease will be created and the server responds with status 201.

I am unsure how to handle this case when no tasks are available. It is not possible to create a lease, when no tasks are available. Which HTTP status code would be appropriate for this case?

• 204 No Content – The client hasn’t made anything wrong, but there is no data.

• 400 Bad Request – This is imho not applicable, as it means “the request could not be understood by the server”, which is not the case

In the meantime I thought that this approach might not be ideal. Either I use 503, as recommended of Brian and also backed by a passage of REST in practice, or I change the whole process.

I was thinking of leases which could be created tentatively. That means

1. PUT to /leases
2. Either create a lease, assign a task and respond with 201 or create a tentative lease and respond with 202
3. Tentative leases will stay for some time. If tasks gets available, they are assigned to the tentative leases. If there is no task for a specific period of time, the lease gets deleted and the server will respond with 410
4. The client should then start again with 1.

Answer 1

Since the resource is controlled by the server and there’s nothing the client can do to influence the outcome, a 500-range code would be most appropriate.

503 - Service Unavailable sounds right to me. It implies that the server has not got enough resources available to meet the needs of the request. You should probably also return a meaningful error in the body of the response to make it explicitly clear that it failed because no leases/tasks were available, but that might not be the case sometime in the future.