What Does HTTP Status Code 201 Mean?

HTTP status code 201 means the request succeeded and a new resource was created as a result. Its official name is 201 Created, and it belongs to the 2xx family, which is the family of successful responses.

So a 201 is good news. If your tool, log viewer or monitoring dashboard is showing 201 in red or counting it as a failure, the code is fine and the tool is misreading it.

What is a resource, in the context of a 201?

A resource is whatever the server stores and can hand back later under its own address: a user account, an order, an uploaded file, a comment, a scheduled job. A 201 is the server saying "I made one of those, and it now exists."

That is the difference between 201 and a plain acknowledgement. A 201 is a promise that something persisted, not just that the message was received.

How is 201 different from 200 OK?

Both mean success. The difference is what happened:

• 200 OK means the request worked. It says nothing about anything being created.
• 201 Created means the request worked and something new now exists that did not exist before.
• 204 No Content means the request worked and there is deliberately nothing to send back.

In practice, a POST that creates a record should answer 201, a GET that reads one should answer 200, and a DELETE that removed one often answers 204.

What should a 201 response contain?

By convention, a 201 tells the client where the new thing lives. That means:

• A Location header holding the address of the newly created resource.
• Usually a body containing the created record, including the identifier the server assigned to it.

The identifier matters most. If your client has to guess or re-query to find out what was just created, the API is making work for every caller, and the fix is to return the identifier in the 201.

When do you see a 201 status code?

Most commonly after a POST request that submits a form or calls an API to create something: registering an account, placing an order, uploading a file, adding a row. Some APIs also return 201 from a PUT request when the address you wrote to did not exist yet and the server created it for you.

You will normally only see the number itself in developer tools, in a server log, or in an API client. Ordinary users never see it, because the browser shows the resulting page instead.

Why did I get a 201 but the record is missing?

A 201 is a claim by the server, and claims can be wrong. Work through this order:

1. Check the response body and Location header for the identifier that was assigned, and fetch that exact address.
2. Check that you are reading from the same environment you wrote to. Writing to staging and reading from production is the most common cause.
3. Check for a filter on the list you are looking at: drafts, unpublished items and items owned by another account often do not appear by default.
4. Check whether a background job still has to process the record before it is visible, which is common with uploads and imports.
5. Check the server log for a rollback after the response. A transaction that failed after the status line was sent leaves exactly this symptom.

If the identifier from the 201 does fetch successfully, the record exists and the problem is in the view you were looking at.

Why is my app treating 201 as an error?

Usually because the client checks for equality with 200 instead of checking the range. Any code from 200 to 299 is a success. A check written as "is the status exactly 200" will reject every 201, 202 and 204 the server sends.

The second common cause is a response parser that expects a body in a fixed shape. A 201 with an empty body, or a body containing only the new identifier, can break a parser that assumed a full record. Handle the empty case rather than forcing the server to send something it does not have.

Should my own API return 201 or 200?

Return 201 when the call created something that now has its own address, and include that address. Return 200 when the call succeeded but created nothing, such as a search or a recalculation.

Consistency is worth more than perfection here. An API that returns 200 everywhere is easier to live with than one that returns 201 for half its create endpoints and 200 for the other half, because callers stop being able to reason about the answer.

When does 202 fit better than 201?

202 Accepted means the server took the request but has not finished acting on it, and the thing may not exist yet. Use it for work that goes into a queue: a large import, a video conversion, a report that takes minutes to build.

The practical test is whether a client can immediately fetch the new resource. If yes, that is a 201. If the client would get a 404 for a few seconds or a few minutes, that is a 202, and the response should tell the client where to check on progress.

What should you record before asking for help with a 201?

If a 201 is behaving strangely and you need someone else to look, gather the request method and path, the exact time, the full response headers including Location, the response body, and the identifier of anything that was created. Note which environment you were on.

Almost every "the API says created but nothing was created" ticket is resolved from those five facts, and almost none can be resolved without them.