What status code should we return for this situation?

what_status_code.md

What status code should this return?

I'm working on an HTTP-compliant API for a service. We've got a situation where we're not sure what status code to return.

In our system, users create "campaigns" to track data they care about. From the point they create a campaign, it can take a while (e.g. multiple days) before the first batch of data is ready.

During this time before the first batch is ready, when a client an endpoint requesting data for a not-yet ready campaign, what status code should be returned? I can't think of any existing status code that readily applies to this situation. In fact, this situation doesn't even seem to fit into any of the status "families":

• It's obviously not a 1xx response -- these are more meant more at the protocol layer than for application semantics.
• 2xx success -- we can't successfully respond to the request because we don't yet have the data the client is requesting.
• 3xx redirection -- we don't have anywhere to redirect the client to.
• 4xx client error -- the client hasn't made an error here. the resource simply isn't ready yet.
• 5xx server error -- it's not a server error, either.

Part of me thinks that 404 is the right response, since the resource cannot (yet) be found...but that kinda implies that the URL is wrong, when the URL is in fact correct--it's just not ready yet. And this isn't really a client error, as I mentioned above.

Another idea is returning a 200 success response, with a payload that is different from the normal success payload--the payload would have an attribute indicating why no requested data is returned. I think this would kinda suck for clients, though; a normal pattern folks follow is:

response = client.make_request
if response.status == 200
  # do something that assumes that the response includes the requested data
end

...but this would pattern would no longer work...clients would now have to do:

response = client.make_request
if response.status == 200 && response['did_it_really_succeed?'] == true
  # do something that assumes that the response includes the requested data
end

...which seems lame.

Thoughts?

The action by the client was creating something with the POST. The server is using its own namespace to say "hey, I made this over there." 🤷

404 seems outright wrong. Either a 202 or a 204 with an explanation in the payload and in the API docs would make sense to me.

The 200 with an explanation in the payload seems analogous to rescuing an exception in ruby and having to look at the message to see what to actually do with it; it's messy and always feels like there should be a more clear distinction made.