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.
| Class | Meaning | Who has to act |
|---|---|---|
| 1xx | Informational: the request was received, the process continues | Usually nobody |
| 2xx | Successful: the request was received, understood and accepted | Your code reads the body |
| 3xx | Redirection: further action is needed to complete the request | Your client follows the new location |
| 4xx | Client error: the request has a problem | You fix the request |
| 5xx | Server error: the server failed to fulfil a valid request | The 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.
| Code | Name | What it says |
|---|---|---|
| 200 | OK | The request succeeded; the content depends on the method. |
| 201 | Created | The request succeeded and made one or more new resources. |
| 204 | No Content | Success, and there is no body to send. |
| 301 | Moved Permanently | The resource has a new permanent address. |
| 302 | Found | The resource is temporarily at another address; keep using the old one. |
| 304 | Not Modified | A conditional request found nothing new; use your cached copy. |
| 307 | Temporary Redirect | Like 302, but the client must not change the method. |
| 308 | Permanent Redirect | Like 301, but the client must not change the method. |
| 400 | Bad Request | The server cannot or will not process what it sees as a client error, such as broken syntax. |
| 401 | Unauthorized | The request lacks valid authentication credentials. |
| 403 | Forbidden | The server understood the request and refuses to fulfil it. |
| 404 | Not Found | The server has no current representation of the target resource. |
| 405 | Method Not Allowed | The method is known but not supported for this resource. |
| 409 | Conflict | The request conflicts with the current state of the resource. |
| 410 | Gone | The resource is no longer available and probably never will be. |
| 415 | Unsupported Media Type | The server does not support the format of the request content. |
| 422 | Unprocessable Content | The syntax is right, but the server cannot process the instructions inside. |
| 429 | Too Many Requests | You sent too many requests in a given time; a Retry-After header may say how long to wait. |
| 500 | Internal Server Error | The server hit an unexpected condition. |
| 501 | Not Implemented | The server does not support the function the request needs. |
| 502 | Bad Gateway | A gateway or proxy received an invalid response from the upstream server. |
| 503 | Service Unavailable | The server cannot handle the request now, for example from overload or maintenance. |
| 504 | Gateway Timeout | A 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.
| Method | Safe | Idempotent | Typical use in a REST-style API |
|---|---|---|---|
| GET | Yes | Yes | Read a resource or a list |
| HEAD | Yes | Yes | Read headers only |
| OPTIONS | Yes | Yes | Ask which methods a resource supports |
| PUT | No | Yes | Replace a resource with the content you send |
| DELETE | No | Yes | Remove a resource |
| POST | No | No | Create a resource or start an action |
| PATCH | No | No | Change 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
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.