Introduction
When working with APIs, one of the first things developers encounter is the HTTP status code returned by the server. Codes such as 200, 201, 400, 401, 404, and 500 quickly tell you whether a request succeeded, was redirected, failed because of the client, or encountered a server-side problem.
Understanding these status codes makes API development, testing, and debugging much easier. Instead of guessing what went wrong, you can use the status code as your first clue and then investigate the request, authentication, parameters, server logs, or upstream services.
In this article, we'll break down the most commonly used API status codes with simple explanations and real-world examples, along with a quick debugging rule you can remember.
🟢 2xx — Success
Your request worked.
The server successfully processed the request.
✅ 200 — OK
The request succeeded.
Example
GET /api/users/123
200 OK
Usually means the requested operation completed successfully and the response contains the requested data.
✅ 201 — Created
A new resource was successfully created.
Example
POST /api/users
201 Created
Commonly returned after creating a new record, user, order, invoice, etc.
✅ 204 — No Content
The request succeeded, but there is no response body to return.
Example
DELETE /api/users/123
204 No Content
Think:
Success, but nothing to return.
🔵 3xx — Redirection
The resource or response needs another route.
These responses are often related to redirects or caching.
➡️ 301 — Moved Permanently
The requested URL has permanently changed.
Example:
/api/old-users
↓
/api/users
The client should use the new URL.
➡️ 302 — Found / Temporary Redirect
The requested resource is temporarily available at another URL.
The original URL may become valid again later.
🔄 304 — Not Modified
The resource has not changed since the client's cached version.
Instead of sending the resource again, the client can use its cached copy.
Think:
"Nothing changed. Use your cached version."
🟠 4xx — Client Error
Something is wrong with the request from the client side.
This category is especially important when debugging APIs.
⚠️ 400 — Bad Request
The server cannot process the request because the request is invalid or malformed.
Common causes:
Invalid JSON
Missing required fields
Invalid parameters
Incorrect request format
Example:
{
"email": "not-an-email"
}
If the API expects a valid email address, it may return:
400 Bad Request
🔐 401 — Unauthorized
The client is not authenticated or the authentication credentials are missing/invalid.
Common causes:
Think:
"Who are you?"
🚫 403 — Forbidden
The request is understood and the client may be authenticated, but it does not have permission to access the resource.
Think:
"I know who you are, but you aren't allowed to do this."
This is an important distinction:
401 → Authentication problem
403 → Permission problem
🔎 404 — Not Found
The requested resource cannot be found.
Possible causes:
Incorrect URL
Wrong endpoint
Resource doesn't exist
Incorrect ID
Deleted resource
Example:
GET /api/users/99999
404 Not Found
⚔️ 409 — Conflict
The request conflicts with the current state of the resource.
For example, you may try to create a record that already exists or update a resource whose current state conflicts with your request.
Example:
POST /api/users
409 Conflict
⚠️ 422 — Unprocessable Content
The request is syntactically valid, but the data fails semantic validation.
Example:
{
"age": -5
}
The JSON is valid, but the value may not satisfy the API's business rules.
Think:
"I understand your request, but the data doesn't make sense."
⏱️ 429 — Too Many Requests
The client has sent too many requests within a certain period.
This is commonly associated with rate limiting.
Example:
429 Too Many Requests
Possible solution:
Wait before retrying
Implement retry logic
Use exponential backoff
Reduce request frequency
🔴 5xx — Server Error
The request reached the server, but something went wrong while processing it.
These errors generally indicate a problem on the server or with an upstream service.
🔥 500 — Internal Server Error
A generic server-side error occurred.
Possible causes:
Think:
"The server broke while processing your request."
🌐 502 — Bad Gateway
A server acting as a gateway or proxy received an invalid response from an upstream server.
Example:
Client
↓
API Gateway
↓
Backend Service ❌
The gateway cannot get a valid response from the backend.
🚧 503 — Service Unavailable
The server is temporarily unable to handle the request.
Common causes include:
Server overload
Maintenance
Temporary service outage
A Retry-After header may be provided when the service expects to recover later.
⏳ 504 — Gateway Timeout
A gateway or proxy did not receive a response from an upstream server within the expected time.
Example:
Client
↓
API Gateway
↓
Backend
⏳
The upstream service took too long to respond.
🧠 The 3-Second API Debugging Rule
When you see an API status code, start with the first digit.
🟢 2xx
Your request succeeded.
Check the response data if something still looks wrong.
🔵 3xx
Check the URL or caching.
Look for redirects, the Location header, or cached responses.
🟠 4xx
Check your request.
Look at:
URL
HTTP method
Parameters
Request body
Headers
Authentication
Permissions
🔴 5xx
Investigate the server or upstream service.
Check:
📌 Quick Cheat Sheet
| Code | Meaning | Think |
|---|
| 200 | OK | Request succeeded |
| 201 | Created | New resource created |
| 204 | No Content | Success, nothing to return |
| 301 | Moved Permanently | URL changed permanently |
| 302 | Found | Temporary redirect |
| 304 | Not Modified | Use cached version |
| 400 | Bad Request | Invalid request |
| 401 | Unauthorized | Authentication problem |
| 403 | Forbidden | Permission problem |
| 404 | Not Found | Resource/endpoint missing |
| 409 | Conflict | State conflict |
| 422 | Unprocessable Content | Validation/business-rule failure |
| 429 | Too Many Requests | Rate limit reached |
| 500 | Internal Server Error | Server-side failure |
| 502 | Bad Gateway | Upstream response problem |
| 503 | Service Unavailable | Server unavailable/overloaded |
| 504 | Gateway Timeout | Upstream response too slow |
🎯 Easy Way to Remember
2xx → SUCCESS ✅
3xx → REDIRECT 🔄
4xx → YOUR REQUEST HAS A PROBLEM ⚠️
5xx → SERVER HAS A PROBLEM 🔥
When debugging an API, don't just look at the status code.
Also check the response body, request URL, HTTP method, headers, authentication, parameters, and server logs.
A status code tells you what category of problem occurred. The response body and logs usually tell you why.
📌 Save this cheat sheet. It can save you a lot of debugging time during API development and testing.
Conclusion
Understanding API status codes is an essential skill for every developer working with web services and integrations. By simply looking at the first digit, you can quickly identify whether the request was successful (2xx), redirected (3xx), rejected because of the request (4xx), or affected by a server-side issue (5xx).
The next time an API call fails, use the status code as your first debugging clue. Check the request, authentication, parameters, permissions, server logs, and upstream services based on the error category. With these basics, API troubleshooting becomes faster, clearer, and much less frustrating.