🧩 Standardizing API Responses in Laravel Using HTTP Status Codes

Build Consistent, Clear, and RESTful APIs with Proper Status Code Usage

When building RESTful APIs in Laravel, handling HTTP responses correctly is critical for ensuring that your clients understand the result of each request. One best practice is using HTTP status code constants instead of hardcoded values like 200, 404, or 500 throughout your code.

❌ Bad Example: UserController with Poor Use of Status Codes

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User;

class UserController extends Controller
{
    public function show($id)
    {
        $user = User::find($id);

        if (!$user) {
            // ❌ Using 200 OK for not found
            return response()->json([
                'message' => 'User not found'
            ], 200);
        }

        return response()->json([
            'message' => 'User found',
            'user' => $user
        ], 200);
    }

    public function store(Request $request)
    {
        if (!$request->has('email')) {
            // ❌ No validation, wrong status code
            return response()->json([
                'error' => 'Missing email'
            ], 500);
        }

        $user = User::create([
            'name' => $request->name,
            'email' => $request->email
        ]);

        // ❌ Wrong status code for resource creation
        return response()->json([
            'message' => 'User created',
            'user' => $user
        ], 200);
    }

    public function delete($id)
    {
        $user = User::find($id);

        if (!$user) {
            // ❌ Inconsistent structure and wrong status
            return [
                'status' => false,
                'msg' => 'Not found'
            ];
        }

        $user->delete();

        // ❌ Response missing HTTP structure and status
        return 'User deleted';
    }
}

🚫 Avoid Hardcoding Status Codes

Instead of:

return response()->json(['error' => 'Unauthorized'], 401);

Use:

return response()->json(['error' => 'Unauthorized'], Response::HTTP_UNAUTHORIZED);

There are two main approaches

✅ 1. Use Symfony’s Predefined Constants (Recommended)

namespace App\Http\Controllers;

use Illuminate\Http\Request;
use App\Models\User;
use Illuminate\Support\Facades\Validator;
use Symfony\Component\HttpFoundation\Response;

class UserController extends Controller
{
    // GET /api/users/{id}
    public function show($id)
    {
        $user = User::find($id);

        if (!$user) {
            return response()->json([
                'status' => false,
                'message' => 'User not found'
            ], Response::HTTP_NOT_FOUND); // 404
        }

        return response()->json([
            'status' => true,
            'message' => 'User found',
            'data' => $user
        ], Response::HTTP_OK); // 200
    }

    // POST /api/users
    public function store(Request $request)
    {
        $validator = Validator::make($request->all(), [
            'name'  => 'required|string|max:255',
            'email' => 'required|email|unique:users,email',
        ]);

        if ($validator->fails()) {
            return response()->json([
                'status' => false,
                'message' => 'Validation failed',
                'errors' => $validator->errors()
            ], Response::HTTP_UNPROCESSABLE_ENTITY); // 422
        }

        $user = User::create($request->only(['name', 'email']));

        return response()->json([
            'status' => true,
            'message' => 'User created successfully',
            'data' => $user
        ], Response::HTTP_CREATED); // 201
    }

    // DELETE /api/users/{id}
    public function destroy($id)
    {
        $user = User::find($id);

        if (!$user) {
            return response()->json([
                'status' => false,
                'message' => 'User not found'
            ], Response::HTTP_NOT_FOUND); // 404
        }

        $user->delete();

        return response()->json([
            'status' => true,
            'message' => 'User deleted successfully'
        ], Response::HTTP_NO_CONTENT); // 204 (Note: no body is recommended)
    }
}

✅ 2. Create Your Own Status Code Constants (Optional)

If you want to keep your constants centralized, you can create a custom class like this:

Step 1: Create a file

app/Constants/HttpStatus.php

namespace App\Constants;

class HttpStatus
{
    public const OK = 200;
    public const CREATED = 201;
    public const NO_CONTENT = 204;
    public const BAD_REQUEST = 400;
    public const UNAUTHORIZED = 401;
    public const FORBIDDEN = 403;
    public const NOT_FOUND = 404;
    public const CONFLICT = 409;
    public const INTERNAL_SERVER_ERROR = 500;
}

Step 2: Use it in your code

use App\Constants\HttpStatus;

return response()->json([
    'message' => 'Unauthorized access'
], HttpStatus::UNAUTHORIZED);

🧠 Best Practices

✅ Use Symfony\Component\HttpFoundation\Response constants
✅ Avoid magic numbers (like 200, 404)
✅ Return descriptive messages in JSON
✅ Use custom app-level codes only if needed

🏁 Conclusion

Using HTTP status code constants in Laravel is not just about cleaner syntax — it's about writing professional, reliable, and scalable APIs.