API Status Code Explainer

What Are API Status Codes?

API status codes are standardized codes sent by a server in response to a client request. They indicate whether the request was successful, redirected, or encountered an error.

Common categories include:

• 1xx – Informational: Request received, processing ongoing.
• 2xx – Success: Request was successfully processed (e.g., 200 OK, 201 Created).
• 3xx – Redirection: Further action required to complete the request (e.g., 301 Moved Permanently, 307 Temporary Redirect).
• 4xx – Client Errors: Request was invalid or cannot be processed (e.g., 400 Bad Request, 404 Not Found, 401 Unauthorized).
• 5xx – Server Errors: Server failed to process a valid request (e.g., 500 Internal Server Error, 503 Service Unavailable).

Why It Matters

Monitoring API status codes is crucial for application reliability, uptime, and user experience. Frequent 5xx errors indicate server instability, while 4xx errors may signal issues in client requests or integration problems.

Keeping track of API responses helps you:

• Detect downtime or server issues promptly.
• Ensure smooth client integration and app functionality.
• Identify misconfigured endpoints or broken requests.
• Maintain a stable experience for your users and reduce potential revenue loss.

Tips for Handling API Status Codes

• Regularly monitor your API endpoints for 4xx and 5xx errors with automated checks.
• Ensure proper authentication and request formatting to avoid avoidable client errors.
• Set up retries with exponential backoff for transient server errors like 502, 503, and 504.
• Use uptime and API monitoring tools to detect recurring issues quickly and trace patterns.
• Distinguish between client errors (your bug) and server errors (their bug) when reporting issues.
• Always log the full response body for 4xx and 5xx responses — the body usually contains a useful error message.

REST API Status Codes in Practice

REST APIs use HTTP status codes to communicate the outcome of every request. While the standards define dozens of codes, well-designed APIs use a focused subset consistently. Knowing which code to expect (and which to return) is essential for building reliable integrations.

Success Responses (2xx)

• 200 OK: The request succeeded. Used for GET, PUT, PATCH, and DELETE responses that return content.
• 201 Created: A new resource was successfully created in response to a POST or PUT request. The response should include a Location header pointing to the new resource.
• 202 Accepted: The request has been accepted for processing but is not yet complete. Common for asynchronous operations.
• 204 No Content: The request succeeded, but the server is intentionally returning no body. Common for DELETE operations.

Client Errors (4xx)

• 400 Bad Request: The request is malformed — invalid JSON, missing required fields, wrong types. The response body should explain what is wrong.
• 401 Unauthorized: The request lacks valid authentication credentials. The client should re-authenticate.
• 403 Forbidden: The client is authenticated but does not have permission to access this resource.
• 404 Not Found: The requested resource does not exist. May also indicate a typo in the endpoint URL.
• 405 Method Not Allowed: The HTTP method is not supported for this endpoint (e.g., POST to a read-only resource).
• 409 Conflict: The request conflicts with the current state of the resource — for example, trying to create a record that already exists.
• 422 Unprocessable Entity: The request is well-formed but semantically invalid. Common for validation errors in REST APIs.
• 429 Too Many Requests: The client has exceeded its rate limit. The response should include a Retry-After header.

Server Errors (5xx)

• 500 Internal Server Error: A generic server-side error. Indicates a bug or unexpected condition. Should be rare in a well-tested API.
• 501 Not Implemented: The server does not recognize the request method or lacks the ability to fulfill it.
• 502 Bad Gateway: The server (acting as a proxy or gateway) received an invalid response from an upstream service.
• 503 Service Unavailable: The server is temporarily overloaded or down for maintenance. Often returned with a Retry-After header.
• 504 Gateway Timeout: An upstream server did not respond in time. Common in microservice architectures.

How to Build a Resilient API Client

When you depend on an external API, network glitches, rate limits, and transient errors are inevitable. A well-built API client handles them gracefully instead of failing on the first hiccup. Here are the most important patterns to implement:

• Retry on transient errors with exponential backoff. For 502, 503, 504, and network errors, retry the request after a short delay. Double the delay on each retry to avoid overwhelming a struggling server.
• Respect Retry-After headers. When a server returns 429 or 503 with a Retry-After header, wait at least that long before retrying. Ignoring this is rude and will get you rate-limited harder.
• Set timeouts on every request. Without a timeout, a slow API will eventually exhaust your connection pool and crash your application.
• Use circuit breakers for repeatedly failing endpoints. If an upstream API has been failing for the last 60 seconds, stop sending requests for a while. This prevents you from amplifying the upstream outage.
• Log responses with context. When you log an API error, include the request ID, the endpoint, the status code, and the response body. Future-you will thank present-you.
• Distinguish retryable from non-retryable errors. A 400 will not get better on retry — it is a client bug. A 503 might. Retry only the latter.
• Cache successful responses where appropriate. Many API errors can be avoided entirely by not making the request in the first place.

Monitoring API Health Beyond Status Codes

Status codes are essential, but they only tell part of the story. A complete API monitoring strategy combines them with several other signals:

• Response time: An API that responds with 200 in 30 seconds is functionally broken. Track latency percentiles (p50, p95, p99) and alert when they exceed acceptable thresholds.
• Response body validation: A 200 response with empty or malformed JSON is technically a success but actually a failure. Validate the response shape, required fields, and data types.
• Business-level checks: Does the response contain the expected data? An API that returns "200 OK" with an empty user list when you know the database has users is broken in a way status codes will not catch.
• Error rate trends: Even when individual responses succeed, a steadily increasing error rate is an early warning of degradation.
• Throughput: Sudden drops in successful requests per minute can indicate that something upstream is preventing clients from reaching the API.
• Authentication health: Track 401/403 spikes separately — these often indicate token expiration, certificate issues, or permission bugs.

UptyBots supports both basic API monitoring (HTTP status code checks) and synthetic API monitoring (multi-step flows with response body validation), giving you full visibility into your API's real-world behavior.

Frequently Asked Questions

Should an API ever return a 200 with an error message in the body?

No — and yet many APIs do. A 200 indicates success at the HTTP level. If the operation failed, the API should return an appropriate 4xx or 5xx code so clients (and monitoring tools) can detect the failure without parsing the body. Returning 200 for errors is one of the most common API design mistakes and makes monitoring much harder.

What is the difference between 422 and 400?

400 Bad Request means the request itself is malformed — invalid JSON, missing headers, wrong syntax. 422 Unprocessable Entity means the request is structurally correct but semantically invalid — for example, a valid JSON body that fails business validation rules. Many APIs use them interchangeably, but the distinction is useful when both apply.

How do I handle rate limiting (429)?

When you receive a 429, look for a Retry-After header in the response and wait at least that long before retrying. Implement exponential backoff in your client. If you are hitting rate limits frequently, redesign your usage to batch requests, cache responses, or upgrade to a higher tier with the API provider.

Are 5xx errors always the server's fault?

Almost always, yes. 5xx codes indicate the server failed to process a valid request. The exception is when 5xx errors are triggered by malicious or pathological input that the server should have rejected with a 4xx but did not. In practice, treat all 5xx as server-side problems and report them to the API provider.

Can I monitor my own API status codes with UptyBots?

Yes. Sign up for a free UptyBots account and add your API endpoint as a monitor target. You can configure which status codes count as success, set custom request methods and headers, validate response bodies, and receive alerts the moment something goes wrong.