I'm defining an API and have come across a question I've not had to deal with before. I was wondering what the consensus on here would be for the best status code to use for a response where the result is not known (yet).
To explain, the GET endpoint in question doesn't return a resource, it just a tool to return specific information about known dates.
The backend calendar data it's using to do this is manually loaded in chunks periodically. So if a user makes a query for a date that is beyond (or prior to) the date range that has been loaded, how should the API respond?
Initially i was thinking a 4xx error, but the syntax and query is technically valid. Trying the exact same query at another time (when the data for that date has been loaded) would result in a successful response.
Looking at 5xx errors, non seem to be an ideal match. 503 Service Unavailable looks closest to me, but seems to focus on temporary errors. This situation might last for months potentially. A compounding problem is that the API itself doesn't know when more data will be loaded so we can't easily use the Retry-After header either.
What would you do? Thanks!
The 202 Accepted means that the service successfully accepted the request and there are, as of yet, no problems with it (i.e. no immediate data validation problems), but it can’t create the resource until it does further processing. This response does not promise that the resource will be created, though. So, it’s perfect for pending requests, since a pending request could be rejected while it’s being processed.
It is also importat to append Location header with endpoit serving actual status of the async operation such that client able to monitor it on a peridoic basis.