I've the following endpoint:


and want to create a b with sending POST request to it. If a with given {id} is not found should I response with 404 NOT_FOUND or maybe with 409 CONFLICT?

It is to handle plain a/{id}, the trick is that here a subresource is used.


404 NOT FOUND seems the appropriate response, because the resource with this ID not exists. It's very clear to understand and you are expecting the same response if a/{id} is called.

409 CONFLICT not seems to me the better choice, because in your example you will return a 409 when the parent resource was not found :).

But remembers that the most important thing is be consistent in your API

| improve this answer | |
  • I agree. If you were to try to write to a folder that didn't exist, is it a conflict or a missing folder error? It seems more intuitive this way to me. – Neil Jan 24 '18 at 12:31
  • A "folder" you mean a path that does not exists? – Dherik Jan 24 '18 at 13:05
  • I mean a folder, like on the file system. – Neil Jan 24 '18 at 14:16
  • Can you detail the scenario? Because it depends. If the folder was expected for the server and (for whatever reason) are not there I think this is a server error (5xx) not a client error (4xx). If this folder value was passed by the client to the resource (as the id), is 404. But if the folder was passed in the body this could be anything else (412, 422... something to represent "validation failed: folder does not exists"). It's a good question to ask and discuss. – Dherik Jan 24 '18 at 14:27
  • If you ask the server for file with path /nonexistent/help.html, and the folder /nonexistent doesn't exist, there is only one clear response to this. 404 file not found! There could even exist a /home/help.html, and the response would not differ. This is a REST application clearly, but I see no reason why the logic would change. The parent must exist first. – Neil Jan 24 '18 at 14:42

In addition to @Dherik's answer.

URIs are identifiers, so we have to keep in mind that (/a/{id}/b is an identifier). The URI is meaningless for the WWW, and so is for the HTTP client.

404 is the right answer. In essence, the server is answering

I didn't find any resource with such id. Resource not found 1

Whether the missing resource is parent or child doesn't matter.

We, developers, see hierarchies and paths in the URI, but HTTP clients don't. In other words, HTTP is only meant to be interpreted by HTTP clients but not by humans (devs, end-users, etc).

In case of doubts, don't ask what code makes sense for you (human). Do ask, what code makes sense for the HTTP client. How do you want the HTTP client to behave?

Why? Because some status code causes these clients to perform certain operations. For example, 302. This code usually makes web browsers to redirect to a specific location (URI) informed in the response headers.

This might not be your case, but it's important to be aware. Ultimately, HTTP status codes are addressed to HTTP clients. Not to our applications. Not to persons.

1: 409 is rarely implemented as navigation error. It usually involves the execution of remote operations (delete, update, new, etc). But the URI should exist. Otherwise, 404 will prevail

| improve this answer | |

Your Answer

By clicking “Post Your Answer”, you agree to our terms of service, privacy policy and cookie policy

Not the answer you're looking for? Browse other questions tagged or ask your own question.