HTTP Status Codes & API Debugging: A Complete Reference for Backend and Frontend Engineers

HTTP status codes are three-digit integers returned by servers in the response header to indicate the outcome of a client's request. They are grouped into five classes, each representing a different category of response.

1xx (Informational) — These codes indicate that the server has received the request and is continuing to process it. The most common is 100 Continue, which tells the client that the server has received the request headers and the client should proceed to send the request body. 101 Switching Protocols is used when upgrading from HTTP to WebSocket connections.

2xx (Success) — These codes indicate that the request was successfully received, understood, and accepted. 200 OK is the standard success response. 201 Created confirms that a new resource was created (used after POST requests). 204 No Content indicates success but no response body (common for DELETE requests and PUT updates). 202 Accepted means the request has been queued for asynchronous processing.

3xx (Redirection) — These codes indicate that further action is needed to complete the request. 301 Moved Permanently tells search engines and browsers to update their records. 302 Found (commonly used for temporary redirects) and 307 Temporary Redirect preserve the request method during redirection. 304 Not Modified indicates the cached version is still valid.

4xx (Client Error) — These codes indicate that the client sent an invalid request. 400 Bad Request means malformed syntax. 401 Unauthorized means authentication is required. 403 Forbidden means the authenticated user lacks permission. 404 Not Found means the resource doesn't exist. 409 Conflict indicates the request conflicts with current state. 429 Too Many Requests means rate limiting is in effect.

5xx (Server Error) — These codes indicate that the server failed to process a valid request. 500 Internal Server Error is a generic catch-all. 502 Bad Gateway means an upstream service returned an invalid response. 503 Service Unavailable means the server is temporarily overloaded or under maintenance. 504 Gateway Timeout means an upstream service didn't respond in time.

Correct status code usage is a cornerstone of well-designed REST APIs. Many APIs misuse status codes by returning 200 OK for every response and embedding error information in the response body. This anti-pattern breaks HTTP client libraries, caching layers, monitoring dashboards, and retry logic that depend on status codes to determine request outcomes.

For resource creation (POST), return 201 Created with a Location header pointing to the newly created resource URL. Include the created resource in the response body so the client can read any server-generated fields (like ID, timestamps, or computed defaults) without an additional GET request.

For updates (PUT/PATCH), return 200 OK with the updated resource in the body, or 204 No Content if no response body is needed. If the update fails due to concurrent modification, return 409 Conflict with details about the conflicting state.

For deletion (DELETE), return 204 No Content on success. If the resource has already been deleted, return 404 Not Found (idempotent) or 204 No Content (tolerant) depending on your API's idempotency guarantees.

For validation errors, return 422 Unprocessable Entity (not 400 Bad Request) with a structured error response body listing each invalid field, the validation rule that failed, and a human-readable error message. This distinction matters: 400 means the request is syntactically malformed (can't be parsed), while 422 means the request is syntactically valid but semantically incorrect (parsed successfully but contains invalid values).

Each HTTP error code points to a different category of problem. Understanding the distinction accelerates debugging by narrowing the investigation to the correct layer of the technology stack.

401 Unauthorized — The request lacks valid authentication credentials. Debug by checking: Is the Authorization header present? Is the token format correct (Bearer vs Basic)? Has the token expired? Is the token signed with the correct key? Is the authentication middleware correctly configured? Check server logs for authentication rejection reasons.

403 Forbidden — Authentication succeeded, but the authenticated user lacks permission. Debug by checking: What role or permission is required? Does the user's token contain the necessary claims? Is the resource's access control list (ACL) correctly configured? Are permission checks evaluating the correct scope?

404 Not Found — The requested URL doesn't map to any resource. Debug by checking: Is the URL path correct (case sensitivity matters in most servers)? Does the route/endpoint exist in the router configuration? Has the resource been deleted? Is the ID format correct (UUID vs integer)?

500 Internal Server Error — An unhandled exception occurred in the server code. Debug by checking: server application logs (not just the HTTP response), recent deployments that may have introduced bugs, database connectivity, external service dependencies, and memory/disk resource exhaustion.

502 Bad Gateway — A reverse proxy or load balancer received an invalid response from the upstream application server. Debug by checking: Is the application process running? Is it listening on the expected port? Is the proxy configuration pointing to the correct backend? Has the application crashed and been restarted by the process manager?

503 Service Unavailable — The server is temporarily unable to handle requests. Debug by checking: Is the server under heavy load (CPU/memory exhaustion)? Is there an active deployment or maintenance window? Has a circuit breaker tripped on a critical dependency? Is there a database connection pool exhaustion?

Effective API debugging requires tools that let you construct, send, and inspect HTTP requests with full control over headers, methods, body content, and authentication credentials.

Browser DevTools Network Tab is the first tool for debugging frontend API calls. It shows every HTTP request made by the page, including the full request/response headers, body content, timing breakdown, and status code. Filter by XHR/Fetch to see only API calls. The "Copy as cURL" feature lets you reproduce any request from the command line.

cURL is the universal command-line HTTP client. It supports all HTTP methods, custom headers, request bodies, authentication, cookies, and SSL certificates. Building cURL commands manually is tedious for complex requests — ToolZeno's cURL Command Builder generates correctly formatted commands with proper escaping from a visual interface.

REST API testing tools allow you to save, organise, and replay API requests. ToolZeno's REST Request Builder provides a browser-based interface for constructing requests with visual header and body editors, without requiring software installation or account creation. All request data remains local to your browser.

HTTP Status Lookup tools provide quick reference for unfamiliar status codes encountered during debugging. Rather than searching documentation, ToolZeno's HTTP Status Lookup provides instant descriptions, common causes, and debugging suggestions for every standard HTTP status code.

The critical advantage of browser-based API debugging tools is privacy. When testing against staging or production APIs, request headers contain authentication tokens, API keys, and session cookies. Desktop applications like Postman have faced scrutiny over telemetry and cloud sync features that may transmit API credentials. Client-side browser tools process everything locally with zero data transmission.