A status code is a three-digit number that says how a request went. The first digit gives the class, and is often all you need to know what to do next.
| Class | Meaning | The client should |
|---|---|---|
| 1xx | Informational | Wait for the final response |
| 2xx | Success | Carry on |
| 3xx | Redirection | Follow the new address, or use a cached copy |
| 4xx | The request was wrong | Fix the request. Repeating it unchanged will not help |
| 5xx | The server failed | Retry later, with backoff, if the operation is safe to repeat |
2xx: it worked
| Code | Name | Meaning and typical use |
|---|---|---|
| 200 | OK | The request succeeded, and the response has the result. The default for a successful GET |
| 201 | Created | A new resource was made. The Location header should point to it. The usual answer to a POST that creates |
| 202 | Accepted | Received and will be processed later. Use for work that continues in the background |
| 204 | No Content | Success with nothing to return. Common for DELETE and some updates |
| 206 | Partial Content | Part of a resource, in answer to a range request (resumable downloads, video) |
3xx: look elsewhere
| Code | Name | Meaning and typical use |
|---|---|---|
| 301 | Moved Permanently | The address has changed for good. Browsers and search engines update. The method may change to GET |
| 302 | Found | A temporary move. Historically ambiguous about the method |
| 303 | See Other | After a POST, go and GET another page (the post/redirect/get pattern) |
| 304 | Not Modified | Your cached copy is still valid. Sent in answer to a conditional request (If-None-Match, If-Modified-Since) |
| 307 | Temporary Redirect | A temporary move that keeps the method and body |
| 308 | Permanent Redirect | A permanent move that keeps the method and body |
4xx: the request has a problem
| Code | Name | What it usually means | What to do |
|---|---|---|---|
| 400 | Bad Request | Malformed syntax, an invalid body or parameters | Fix the request |
| 401 | Unauthorized | You are not authenticated, or the credentials are wrong or expired | Send valid credentials. The name is misleading: it is about authentication |
| 403 | Forbidden | Authenticated, but not allowed to do this | Ask for permission. Re-sending the same credentials will not help |
| 404 | Not Found | Nothing at this address (or the server hides that it exists) | Check the URL and the id |
| 405 | Method Not Allowed | The resource does not support this method. The Allow header lists the ones it does |
Use an allowed method |
| 406 | Not Acceptable | The server cannot produce a response in a format you accept | Adjust the Accept header |
| 408 | Request Timeout | The server gave up waiting for the request | Try again |
| 409 | Conflict | The request conflicts with the current state, such as an edit clash or a duplicate | Fetch the current state and resolve |
| 410 | Gone | Existed once and was removed on purpose | Stop using it |
| 412 | Precondition Failed | A condition such as If-Match was not met, often a sign someone else changed it |
Re-fetch and retry |
| 413 | Content Too Large | The body is bigger than the server accepts | Send less, or in parts |
| 415 | Unsupported Media Type | The body's format is not accepted | Check the Content-Type header |
| 422 | Unprocessable Content | The syntax is fine but the content fails validation | Fix the fields named in the error |
| 429 | Too Many Requests | You are being rate-limited. Retry-After may say when to return |
Slow down and wait |
5xx: the server has a problem
| Code | Name | What it usually means | What to do |
|---|---|---|---|
| 500 | Internal Server Error | An unhandled error in the server's code | Retry later; report it if it persists |
| 501 | Not Implemented | The server does not support this feature or method | Do not retry |
| 502 | Bad Gateway | A proxy or gateway received an invalid answer from the server behind it | Retry later |
| 503 | Service Unavailable | Overloaded or down for maintenance. Retry-After may be sent |
Retry with backoff |
| 504 | Gateway Timeout | A proxy waited too long for the server behind it | Retry later; the work may have been done |
Habits that save time
- 401 versus 403. If you do not know who the caller is, return 401. If you know and they are not permitted, return 403.
- Use the specific code. A
422for failed validation and a404for a missing item let the caller react correctly. Returning200with{"error": ...}hides failure from every tool that reads status codes. - Retry only what is safe.
GETand idempotent requests can be retried after 429 and 5xx errors. A blind retry of aPOSTcan create duplicates unless the API supports an idempotency key. - Read the body and the headers. The code gives the category. The body usually carries the details, and headers such as
Location,Retry-AfterandAllowcarry instructions.
References
From Grokem: https://www.grokem.com/programming/apis-integrations/rest/http-status-codes-reference
