HTTP Status Codes in APIs
How Status Codes Summarize an API Response
HTTP status codes in APIs are three-digit numbers in each response that tell the client what happened to its request. Programs use them to react automatically, without parsing the full body to find out whether a call worked.
The first digit gives the broad category. 2xx codes mean success. 3xx codes tell the client to look elsewhere or use a stored copy. 4xx codes mean the client made an error. 5xx codes mean the server failed to complete a request that may have been valid. Monitoring tools and client libraries rely on these categories to decide whether to retry, fix the request or raise an alert.
Some APIs return 200 for every response and place the real outcome inside the body. This makes failures harder to detect, so most APIs use the codes as intended. Each status code is part of the response described in how an API call is structured.
Success Codes: 200 OK Versus 201 Created
200 OK is the general success response. It is typically returned when a GET request retrieves data, or when an update succeeds and returns the updated record.
201 Created is more specific. It means a new resource now exists, usually after a POST request, and the response often includes the address of the new item. 204 No Content means the action succeeded and there is nothing to return, which is common after a DELETE.
Client Errors: 400, 401, 403, 404, 422 and 429
- 400 Bad Request means the request itself is malformed, for example invalid JSON or a missing required header.
- 401 Unauthorized means the caller has not supplied valid credentials. Despite its name, it means the server does not know who is calling.
- 403 Forbidden means the server knows who the caller is but does not allow this action.
- 404 Not Found means no resource exists at that address.
- 422 Unprocessable Content, formerly called Unprocessable Entity, means the request is well formed but its data fails validation, such as an invalid email address. Many APIs use it for form-style errors.
- 429 Too Many Requests means the client has exceeded a rate limit and should wait before retrying. Limits are explained in API rate limiting.
The difference between 400 and 422 is about where the problem lies. A 400 points to the shape of the request, while a 422 points to the content that the request carries.
Server Errors: 500 Internal Server Error and 503
500 Internal Server Error is a generic failure. The server hit an unexpected problem and could not handle it more specifically, which usually points to a bug or fault on the provider's side.
503 Service Unavailable means the server cannot handle requests right now, often because of maintenance or overload. It may include a Retry-After header suggesting when to try again. Clients should wait before retrying a 503 rather than repeating the request immediately, so they do not add load to a struggling service.
As a rule of thumb, a 4xx response means the client should change its request, while a 5xx response means the problem lies with the provider, although a later retry may succeed.
Frequently asked questions
Should an API ever return 200 for an error?
Generally no. A 200 status tells clients the request succeeded, so they process the body as normal data. Some GraphQL services return 200 with errors listed in the body, because one response can contain both data and errors. Most REST-style APIs should use 4xx or 5xx codes so that clients, caches and monitoring tools can detect failures without reading every response.
What is the difference between 401 and 403?
A 401 response means the API could not verify who is calling, usually because credentials are missing, expired or invalid. A 403 response means the API knows the caller but refuses the action, for example because the account lacks permission for that resource. Fixing a 401 means supplying valid credentials. Fixing a 403 means changing the permissions.