DEV Community

ToolBench
ToolBench

Posted on

Understanding HTTP Status Codes Every Developer Should Know (With Real API Examples)

#api #beginners #tutorial #webdev

Understanding HTTP Status Codes Every Developer Should Know (With Real API Examples)

If you've ever integrated an API, you've almost certainly encountered responses like 200 OK, 404 Not Found, or 500 Internal Server Error.

At first, these numbers can seem confusing. But once you understand what each status code means, debugging becomes much easier.

In this article, we'll explore the most common HTTP status codes, when they're returned, and how to respond to them as a developer.

What Are HTTP Status Codes?

HTTP status codes are standardized responses sent by a server after it receives a request from a client (such as a web browser, mobile app, or frontend application).

Every response contains two important pieces of information:

  • The status code
  • The response body (if any)

Example:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "message": "User retrieved successfully"
}
Enter fullscreen mode Exit fullscreen mode

The status code immediately tells you whether the request succeeded or failed.

The Five Categories of Status Codes

HTTP status codes are grouped into five categories.

Range Meaning
1xx Informational
2xx Success
3xx Redirection
4xx Client Errors
5xx Server Errors

Let's look at the ones you'll encounter most often.

200 OK

This is the response every developer wants to see.

It means the request was successful and the server returned the expected data.

Example:

GET /api/users/15

Response

200 OK
Enter fullscreen mode Exit fullscreen mode

Response body

{
  "id": 15,
  "name": "John",
  "email": "john@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Use this when:

  • Fetching users
  • Loading products
  • Retrieving reports
  • Reading configuration data

201 Created

Returned after successfully creating a new resource.

Example:

POST /api/users
Enter fullscreen mode Exit fullscreen mode

Response

201 Created
Enter fullscreen mode Exit fullscreen mode 
{
    "id": 101,
    "name": "Alice"
}
Enter fullscreen mode Exit fullscreen mode

Typical use cases:

  • User registration
  • Creating blog posts
  • Adding products
  • Creating orders

204 No Content

Sometimes an operation succeeds but doesn't need to return any data.

Example:

DELETE /api/users/15
Enter fullscreen mode Exit fullscreen mode

Response

204 No Content
Enter fullscreen mode Exit fullscreen mode

This is commonly used after successful delete operations.

400 Bad Request

The server couldn't process the request because it was invalid.

Common reasons:

  • Missing required fields
  • Invalid JSON
  • Incorrect data types
  • Validation failures

Example:

{
    "email":"not-an-email"
}
Enter fullscreen mode Exit fullscreen mode

Possible response

{
    "error":"Invalid email address"
}
Enter fullscreen mode Exit fullscreen mode

Always validate user input before sending requests.

401 Unauthorized

Authentication is required.

Typical causes:

  • Missing JWT token
  • Expired access token
  • Invalid credentials

Example:

Authorization header missing
Enter fullscreen mode Exit fullscreen mode

Response

401 Unauthorized
Enter fullscreen mode Exit fullscreen mode

403 Forbidden

The user is authenticated but doesn't have permission.

Example:

A normal user tries to access an admin endpoint.

403 Forbidden
Enter fullscreen mode Exit fullscreen mode

Think of it like this:

  • 401 = "Who are you?"
  • 403 = "I know who you are, but you're not allowed."

404 Not Found

Probably the most recognized status code.

It means the requested resource doesn't exist.

Example

GET /api/products/99999
Enter fullscreen mode Exit fullscreen mode

Response

404 Not Found
Enter fullscreen mode Exit fullscreen mode

Possible reasons:

  • Wrong URL
  • Deleted resource
  • Incorrect API version
  • Typo in endpoint

409 Conflict

Returned when a request conflicts with existing data.

Example:

Creating a user with an email address that's already registered.

{
    "email":"john@example.com"
}
Enter fullscreen mode Exit fullscreen mode

Response

409 Conflict
Enter fullscreen mode Exit fullscreen mode

422 Unprocessable Entity

The request is syntactically correct, but the provided data doesn't satisfy business rules.

Example:

{
    "age": -5
}
Enter fullscreen mode Exit fullscreen mode

Response

{
    "error":"Age must be greater than zero."
}
Enter fullscreen mode Exit fullscreen mode

Many modern REST APIs use this status code for validation errors.

500 Internal Server Error

This indicates something went wrong on the server.

Examples include:

  • Null reference exceptions
  • Database connection failures
  • Unexpected exceptions
  • Configuration issues

Example response

500 Internal Server Error
Enter fullscreen mode Exit fullscreen mode

If you're building APIs, avoid exposing stack traces to clients. Instead, log the error internally and return a meaningful message.

503 Service Unavailable

The server is temporarily unavailable.

Possible reasons:

  • Scheduled maintenance
  • High traffic
  • Database outage
  • Dependency failure

Unlike a 500 error, a 503 often indicates the service may recover shortly.

Quick Reference

Status Meaning
200 Success
201 Resource created
204 Success, no response body
400 Bad request
401 Authentication required
403 Permission denied
404 Resource not found
409 Conflict
422 Validation/business rule failure
500 Internal server error
503 Service temporarily unavailable

Best Practices

  • Use the correct status code instead of always returning 200.
  • Return clear, consistent error messages.
  • Validate input before processing requests.
  • Log server-side exceptions for troubleshooting.
  • Avoid exposing sensitive implementation details in error responses.
  • Document expected status codes in your API documentation.

Final Thoughts

Understanding HTTP status codes is one of the simplest ways to become more effective at debugging APIs and building reliable applications. Choosing the right response code also makes your APIs easier for other developers to integrate with and troubleshoot.

Which HTTP status code do you encounter most often in your day-to-day development? Share your experience in the comments—I’d love to hear your stories and debugging tips.

Explore More Developer Tools

If you regularly work with APIs, JSON, encoding, formatting, or debugging, check out ToolBenchApp: https://toolbenchapp.com/.

It's a growing collection of free browser-based developer tools designed to simplify everyday development tasks—whether you're formatting JSON, validating data, decoding JWTs, comparing text, or converting common formats. If you have ideas for a tool that would make your workflow easier, I'd love to hear your suggestions.

Top comments (1)

Collapse
 
luis_cruzy profile image
Luis Cruzy •

I found the explanation of the 401 and 403 status codes to be particularly helpful, as it can be easy to get these two mixed up. I appreciate the analogy "401 = 'Who are you?' and 403 = 'I know who you are, but you're not allowed'" - it makes the distinction very clear. One question I do have is how to handle cases where a user's access token has expired, but they are still logged in - should we return a 401 in this case, or is there a better approach?