API basics · reviewed November 2026

HTTP Status Codes for API Developers: What Each One Means and What to Do Next

Every response from a web API starts with a three-digit status code. This page explains the codes you will meet most often, using the wording of the HTTP standard (RFC 9110), and it includes a lookup tool that tells you what a code means and whether your client should retry the request.

The anatomy of an API call

An HTTP API call has two halves. The request names a resource with a URL, picks a method such as GET or POST, adds headers, and sometimes carries a body. The response returns a status code, headers and usually a JSON body.

The first digit of the status code gives its class. RFC 9110 says a client must understand the class of any code, even one it does not recognize.

ClassMeaningWho has to act
1xxInformational: the request was received, the process continuesUsually nobody
2xxSuccessful: the request was received, understood and acceptedYour code reads the body
3xxRedirection: further action is needed to complete the requestYour client follows the new location
4xxClient error: the request has a problemYou fix the request
5xxServer error: the server failed to fulfil a valid requestThe API provider fixes it; you may retry

For example, if you receive the undefined code 471, treat it like 400, as RFC 9110 explains.

The 23 codes worth memorizing

Most APIs reuse the same small set of codes. The table paraphrases the wording of RFC 9110, except 429, which comes from RFC 6585.

CodeNameWhat it says
200OKThe request succeeded; the content depends on the method.
201CreatedThe request succeeded and made one or more new resources.
204No ContentSuccess, and there is no body to send.
301Moved PermanentlyThe resource has a new permanent address.
302FoundThe resource is temporarily at another address; keep using the old one.
304Not ModifiedA conditional request found nothing new; use your cached copy.
307Temporary RedirectLike 302, but the client must not change the method.
308Permanent RedirectLike 301, but the client must not change the method.
400Bad RequestThe server cannot or will not process what it sees as a client error, such as broken syntax.
401UnauthorizedThe request lacks valid authentication credentials.
403ForbiddenThe server understood the request and refuses to fulfil it.
404Not FoundThe server has no current representation of the target resource.
405Method Not AllowedThe method is known but not supported for this resource.
409ConflictThe request conflicts with the current state of the resource.
410GoneThe resource is no longer available and probably never will be.
415Unsupported Media TypeThe server does not support the format of the request content.
422Unprocessable ContentThe syntax is right, but the server cannot process the instructions inside.
429Too Many RequestsYou sent too many requests in a given time; a Retry-After header may say how long to wait.
500Internal Server ErrorThe server hit an unexpected condition.
501Not ImplementedThe server does not support the function the request needs.
502Bad GatewayA gateway or proxy received an invalid response from the upstream server.
503Service UnavailableThe server cannot handle the request now, for example from overload or maintenance.
504Gateway TimeoutA gateway or proxy did not get a timely response from the upstream server.

Source: IETF RFC 9110, HTTP Semantics, section 15; IETF RFC 6585, section 4 (code 429).

Methods decide what is safe to repeat

A retry is only harmless when repeating the request has the same effect as sending it once. RFC 9110 calls that property idempotent. It also defines safe methods, which are essentially read-only.

MethodSafeIdempotentTypical use in a REST-style API
GETYesYesRead a resource or a list
HEADYesYesRead headers only
OPTIONSYesYesAsk which methods a resource supports
PUTNoYesReplace a resource with the content you send
DELETENoYesRemove a resource
POSTNoNoCreate a resource or start an action
PATCHNoNoChange part of a resource

Source: RFC 9110, sections 9.2.1 and 9.2.2 (safe and idempotent methods); RFC 5789 states that PATCH is neither safe nor idempotent as HTTP defines those terms, although a PATCH request can be written so that it is idempotent.

Status code lookup and retry advisor

Enter a code to see its meaning.

Method: the name and meaning come from the table above. For a code the tool does not list, it applies the RFC 9110 rule and reads the code as the x00 code of its class. The retry advice is this page's rule of thumb, built on the idempotent-method definition: it is not a rule from any one API provider, so read your provider's documentation too.

Why the method matters for a retry

If a GET times out, sending it again cannot do harm. If a POST that creates an order times out, a blind retry can create a second order. Many providers offer an idempotency key for that case; check the documentation of yours.

Frequently asked questions

What is the difference between 401 and 403?

A 401 says the request lacks valid authentication credentials. A 403 says the server understood the request and refuses to fulfil it, so the client should not automatically repeat the request with the same credentials.

Should I retry a 500 error?

Only with care. A 500 means the server hit an unexpected condition. Retrying is reasonable for idempotent methods such as GET, PUT and DELETE, with a growing delay between attempts. For POST and PATCH, check the state first or use an idempotency key if the API supports one.

What does a 429 status code mean?

RFC 6585 defines 429 Too Many Requests: you sent too many requests in a given amount of time. The response may carry a Retry-After header that says how long to wait before you try again.

Is 204 an error because the body is empty?

No. A 204 No Content is a success code. The server did the work and has nothing to send back, which is common after a delete or an update.

About this site

iapi.best is an independent informational site about how web APIs work. It sells nothing, takes no payment and recommends no vendor. Definitions come from the IETF documents RFC 9110, RFC 6585 and RFC 5789, each named where used. Last reviewed: November 2026. Educational content, not professional advice.