HTTP Status Codes for API Developers

HTTP status codes are the first signal your API sends about whether a request succeeded. They are also one of the primary signals that uptime monitoring tools use to determine whether an endpoint is healthy. Understanding what each code means — and how your monitoring configuration should respond to it — is practical knowledge for anyone running a production API.

This guide covers the status codes you will actually encounter in production, what they mean from both an API design and an operations perspective, and how to configure your monitoring checks accordingly.

The Five Status Code Classes

HTTP status codes are divided into five classes, each identified by the first digit:

1xx — Informational: Request received, continuing process. Rarely seen in practice.
2xx — Success: The request was received, understood, and accepted.
3xx — Redirection: Further action is needed to complete the request.
4xx — Client Error: The request contains bad syntax or cannot be fulfilled.
5xx — Server Error: The server failed to fulfill an apparently valid request.

For monitoring purposes, the 2xx, 4xx, and 5xx classes are the ones that matter most.

2xx: Success Codes

200 OK

The standard success response. The request succeeded, and the response body contains the requested data. This is what your monitoring tool expects to see for most GET endpoints.

Monitoring implication: A 200 status is a necessary but not sufficient condition for a healthy endpoint. An API returning 200 {"error": "database_unavailable"} is not healthy. Configure your monitoring to validate the response body, not just the status code.

201 Created

The request succeeded and a new resource was created. Used for POST endpoints that create resources.

Monitoring implication: Monitoring a POST endpoint is tricky because you usually do not want to create test data on every check cycle. Options: use a dedicated non-persistent test endpoint, use a GET endpoint on the same resource, or only validate the endpoint is accepting the request structure (returns 400 on malformed input, not a 500).

204 No Content

The request succeeded, but there is no response body. Common for DELETE endpoints and PUT/PATCH operations that do not return the updated resource.

Monitoring implication: If your monitoring tool checks for response body content, configure it to accept an empty body for 204 responses. Do not add body validation to endpoints expected to return 204.

202 Accepted

The request has been accepted for processing, but the processing is not complete. Used for asynchronous operations where the work is queued rather than executed synchronously.

Monitoring implication: A 202 response to a POST that queues a job means the API is healthy for request acceptance, but does not confirm the job actually processes. Monitor your queue health separately.

3xx: Redirect Codes

301 Moved Permanently

The resource has been permanently moved to a new URL. Browsers and HTTP clients follow this automatically, but monitoring tools may not — or may not record the final destination.

Monitoring implication: If your endpoint returns a 301, check whether your monitoring tool follows redirects. Some tools record the 301 and mark the check as failed; others follow the redirect and check the final response. Configure explicitly based on your intent. If you are redirecting HTTP to HTTPS, the monitoring tool should follow the redirect and check the HTTPS endpoint.

302 Found / 307 Temporary Redirect

Temporary redirect. The same concern applies as with 301.

4xx: Client Error Codes

These indicate the request itself was malformed or unauthorized — the server received the request and rejected it based on what was in the request.

400 Bad Request

The server could not understand the request due to invalid syntax, missing required parameters, or invalid parameter values.

Monitoring implication: A 400 in response to a well-formed monitoring check request indicates a problem with either the check configuration or the endpoint's validation logic. If you see unexpected 400s in your monitoring data, review the request your monitor is sending and confirm it matches what the endpoint expects.

401 Unauthorized

Authentication credentials were missing or invalid.

Monitoring implication: If your monitoring tool is checking an authenticated endpoint, you need to include valid credentials. Either use an API key with a long expiry time dedicated to monitoring, or check a public endpoint that exercises the same infrastructure. Never use a real user's credentials for monitoring — use a dedicated monitoring account or API key.

If an endpoint that should be public starts returning 401, that is an authentication middleware misconfiguration and should alert.

403 Forbidden

The server understood the request but refuses to authorize it. The credentials are valid but do not have the necessary permissions.

Monitoring implication: Similar to 401 — check whether your monitoring credentials have the right permissions. A 403 on an endpoint that should be accessible is a legitimate alert condition.

404 Not Found

The requested resource could not be found.

Monitoring implication: A 404 from an endpoint that previously returned 200 indicates one of: a route was removed or renamed, a required resource was deleted, or a deployment broke something in routing. All of these are worth alerting on.

422 Unprocessable Entity

The request was well-formed but contained semantic errors — for example, a JSON body that passes structural validation but fails business logic validation.

Monitoring implication: If your monitoring check sends a request body, a 422 may indicate that the check's test data does not match the endpoint's current validation rules. Update the check configuration if the API's validation logic changed intentionally.

429 Too Many Requests

The client has sent too many requests in a given amount of time (rate limiting).

Monitoring implication: A monitoring tool that checks your endpoint every minute from multiple locations should generally not hit rate limits — most APIs allow far more than 1–2 requests per minute from a given IP. If you see 429s in your monitoring data, either the rate limit is extremely aggressive (unusual), or multiple monitoring systems are checking the same endpoint and their combined traffic is triggering the limit.

Exclude monitoring IPs from rate limiting, or use a dedicated monitoring path that bypasses rate limiting (with appropriate security controls).

5xx: Server Error Codes

These indicate the server encountered an error and could not complete the request — the problem is on the server side.

500 Internal Server Error

The generic "something went wrong on the server" response. Usually indicates an unhandled exception.

Monitoring implication: A 500 from any production endpoint is always alertable. Configure your monitoring to treat 500 responses as failures regardless of your other criteria. Set up error tracking (Sentry, Bugsnag) alongside uptime monitoring to capture the stack trace when 500s occur — the monitoring tool tells you that the endpoint is failing, the error tracker tells you why.

502 Bad Gateway

The server was acting as a gateway (reverse proxy) and received an invalid response from the upstream server.

Monitoring implication: In a typical production deployment, a 502 means your web server (Nginx, Apache) is running but cannot reach your application server (PHP-FPM, Node.js process, etc.). The application server crashed, ran out of workers, or the socket connection broke. This is a genuine outage condition — alert immediately.

503 Service Unavailable

The server is temporarily unable to handle the request, usually due to being overloaded or down for maintenance.

Monitoring implication: A 503 can be intentional (maintenance mode, planned deployment) or unintentional (overload, crash). Configure maintenance windows in your monitoring tool to suppress incidents during planned 503 periods. An unexpected 503 should always alert.

In Laravel, php artisan down puts the application into maintenance mode and causes all requests to return 503. If you forget to run php artisan up after a deployment, your monitoring will helpfully remind you within the next check cycle.

504 Gateway Timeout

The server was acting as a gateway and did not receive a timely response from the upstream server.

Monitoring implication: Similar to 502, but the upstream server is reachable but slow — it received the request and did not respond within the timeout period. Common causes include slow database queries, N+1 query problems, or external API calls timing out. The response time in the monitoring check will be at or near the gateway's configured timeout (often 60 seconds by default).

Configuring Your Monitoring for Each Code

A practical configuration guide for monitoring checks:

What you expect	What triggers an alert	What to check
200 with specific body	Any non-200, or missing body content	Health and business endpoints
200 or 201	Any 4xx or 5xx	POST creation endpoints
204	Any 4xx or 5xx	DELETE and update endpoints
Following 301 → 200	Final destination non-200	Redirected endpoints

The key principle: define success explicitly rather than accepting anything that is not a 5xx. A 404 from an endpoint that should return 200 is a real failure; accepting it silently because it is not a server error misses a legitimate problem.

A Note on Custom Status Codes

Some APIs use non-standard status codes or use standard codes in non-standard ways (returning 200 with an error field in the body is the most common example). When building your API, follow the HTTP spec for status codes — using 200 for everything makes monitoring significantly harder and frustrates API consumers.

When monitoring an API that uses non-standard codes, you may need to rely on body content validation rather than status code checks. A check that verifies "success": true is present in the body is more reliable than a check that looks at the status code alone, for APIs with inconsistent status code usage.

PulseAPI monitors HTTP status codes, response bodies, and response times across multiple regions. Start monitoring free →

HTTP Status Codes Every API Developer Should Know (With Monitoring Implications)