HTTP Status Codes in RESTful APIs

A Complete Guide with Examples

When designing or working with RESTful APIs, understanding HTTP status codes is essential. These codes are the way your backend communicates success or failure back to the client. In this guide, we'll cover:

• What each common status code means
• When to use it
• Examples per HTTP method (GET, POST, PUT, PATCH, DELETE)
• Tables for quick reference

Let's dive into it!

🌐 What Are HTTP Status Codes?

HTTP status codes are standardized numbers returned by a server to indicate the result of a client's request. They are divided into five categories:

✅ 200–299: Successful Responses

200 OK

• Meaning: The request was successful.
• Use cases:
  • GET /products → returns a list of products.
  • GET /products/42 → returns product with ID 42.
  • PUT /users/5 → successful full update.
  • PATCH /users/5 → successful partial update.
• Can return data.

{
  "id": 42,
  "name": "Gaming Laptop",
  "price": 1200.00
}

201 Created

• Meaning: A new resource was created.
• Use case: -POST /products → after creating a new product.
• Should return the created resource or a Location header.

{
  "message": "Product created",
  "id": 123
}

204 No Content

• Meaning: The request was successful but no content is returned.
• Use case:
  • DELETE /products/123
  • PUT /products/123 (if you don’t need to return updated data)
• Response body: Empty

⚠️ 400–499: Client Errors

400 Bad Request

• Meaning: The client sent an invalid request.
• Use cases:
  • Missing required fields in POST or PUT
  • Invalid query parameters
• Example:

{
  "error": "Field 'name' is required"
}

401 Unauthorized

• Meaning: Authentication is required and has failed or not been provided.
• Use case:
  • Missing token or invalid credentials.
• Common with JWT, OAuth.

403 Forbidden

• Meaning: You are authenticated but not authorized to perform the action.
• Use case:
  • Trying to access admin-only endpoints without the right role.

404 Not Found

• Meaning: The requested resource does not exist.
• Use cases:
  • GET /products/999 when product 999 doesn’t exist.
  • DELETE /users/10 if user ID 10 isn’t found.

{
  "error": "Product not found"
}

409 Conflict

• Meaning: The request could not be completed due to a conflict with the current state.
• Use case:
  • Trying to create a user with an email that already exists.

💥 500–599: Server Errors

500 Internal Server Error

• Meaning: Something went wrong on the server side.
• Use case:
  • A database crash
  • Uncaught exception
  • Logic bug
• Avoid returning stack traces in production.

{
  "error": "Internal Server Error"
}

🧩 REST Methods and Expected Status Codes

🧠 Best Practices

• Always return meaningful messages for errors.
• Use consistent formatting:

{ "error": "Message here" }

• Prefer 201 for creations, 204 for deletions.
• Avoid using 500 for validation errors – use 400.
• Add proper logging for 500 errors (but don’t expose internal logs to the client).
• Use middleware to centralize error handling.

🔚 Conclusion

HTTP status codes are not just numbers—they are a language between the frontend and backend. A well-designed API should use them properly to communicate intent, success, or failure. This improves both developer experience and debuggability.