Laravel - Return JSON Along with HTTP Status Code
When you use Response::json() in a standard controller or route closure, Laravel defaults to an HTTP status code of 200 OK. While this is appropriate for successful data retrieval, it fails to distinguish between creating a new resource and simply returning existing data. If your application logic involves POST requests that successfully create a record, sending back a 200 status violates RESTful conventions. Clients expecting a 201 Created might misinterpret the response as a simple success without side effects, potentially leading to optimistic concurrency issues or incorrect frontend handling.
To override this default behavior and explicitly return a 201 status code alongside your JSON payload, you must pass the status code directly into the constructor of the Response facade. The syntax is straightforward: provide the data array first, followed by the specific integer status code.
return Response::json([
'message' => 'Resource created successfully',
'data' => $value,
], 201);
In this example, the second argument 201 forces the HTTP response line to reflect that a new resource has been instantiated. You can also include additional headers or metadata within the array if your API contract requires it, though the status code is the primary indicator of the operation's outcome.
This approach works consistently across Laravel versions from 5.x through the latest 11 and 12 LTS releases. The Response facade remains a reliable utility for crafting raw responses that bypass the default serialization behavior of controller actions returning arrays directly. If you are using the newer syntax where arrays return implicit JSON responses, you can achieve the same result by explicitly invoking response() with the status code:
return response(['hello' => $value], 201);
However, if your goal is to return a specific message string rather than just an integer, Laravel provides the Response facade's json() method which accepts a third optional argument for the status code. Alternatively, you can use the response() helper with a custom status code and a JSON payload array. It is crucial to understand that the status code determines how caching proxies and client applications treat the response. A 201 often includes an ETag or Location header in strict REST implementations, although Laravel does not automatically add these unless explicitly configured via headers.
Consider the trade-offs when choosing between 200 and 201. If you return a 200 after a POST request that modifies state, you signal to the client that nothing new was created. This can cause frontend frameworks like React or Vue to fail their optimistic update strategies because they expect a resource URI in the headers for a 201 response. Conversely, returning a 201 on a GET request would be semantically incorrect and confusing to clients.
If you need to send additional custom headers alongside the JSON body and status code, you can chain the withHeader() method or pass an array of headers into the response constructor depending on the specific Laravel version and helper usage pattern. For instance, setting the Location header is common practice when returning a 201:
return Response::json([
'id' => $newRecord->id,
'message' => 'User created',
], 201)
->withHeader('Location', url('/api/users/' . $newRecord->id));
This ensures that clients can immediately know where to find the newly created resource without needing a separate GET request. Always verify your client's expectations regarding status codes, as some older or non-standard APIs might treat any 2xx code as a generic success regardless of the specific code used.
