HTTP Status Code Reference
A searchable reference of HTTP status codes with guidance on when each is correct and when it is the wrong choice.
Which HTTP status to return, and when each one is the wrong choice.
23 codes
OK
Standard success. The response body carries the result.
Created
A resource was created. Return its location in the Location header.
Accepted
Work was queued and will finish later.
No Content
Success with nothing to return, typically after a DELETE.
Moved Permanently
The resource has a new permanent URL. Caches remember this.
Found
Temporary redirect. Use 307 if the method must be preserved.
Not Modified
The client's cached copy is still good.
Temporary Redirect
Like 302, but the method and body are preserved.
Permanent Redirect
Like 301, but the method and body are preserved.
Bad Request
The request itself is malformed. Do not use it for business rule failures.
Unauthorized
No valid credentials. It means unauthenticated, despite the name.
Forbidden
Authenticated, but not allowed to do this.
Not Found
No such resource. Also used to hide existence from unauthorised callers.
Method Not Allowed
Wrong verb for this path. Include an Allow header.
Conflict
The request clashes with current state, such as a duplicate.
Gone
It existed and was deliberately removed. Stronger signal than 404.
Unsupported Media Type
The Content-Type is not one this endpoint accepts.
Unprocessable Content
Well-formed request, but the values fail validation.
Too Many Requests
Rate limited. Send Retry-After so clients back off correctly.
Internal Server Error
Something broke on the server. Never leak stack traces.
Bad Gateway
An upstream service returned something invalid.
Service Unavailable
Temporarily down or overloaded. Pair with Retry-After.
Gateway Timeout
An upstream service did not answer in time.
200 OK
Standard success. The response body carries the result.
201 Created
A resource was created. Return its location in the Location header.
202 Accepted
Work was queued and will finish later.
204 No Content
Success with nothing to return, typically after a DELETE.
301 Moved Permanently
The resource has a new permanent URL. Caches remember this.
302 Found
Temporary redirect. Use 307 if the method must be preserved.
304 Not Modified
The client's cached copy is still good.
307 Temporary Redirect
Like 302, but the method and body are preserved.
308 Permanent Redirect
Like 301, but the method and body are preserved.
400 Bad Request
The request itself is malformed. Do not use it for business rule failures.
401 Unauthorized
No valid credentials. It means unauthenticated, despite the name.
403 Forbidden
Authenticated, but not allowed to do this.
404 Not Found
No such resource. Also used to hide existence from unauthorised callers.
405 Method Not Allowed
Wrong verb for this path. Include an Allow header.
409 Conflict
The request clashes with current state, such as a duplicate.
410 Gone
It existed and was deliberately removed. Stronger signal than 404.
415 Unsupported Media Type
The Content-Type is not one this endpoint accepts.
422 Unprocessable Content
Well-formed request, but the values fail validation.
429 Too Many Requests
Rate limited. Send Retry-After so clients back off correctly.
500 Internal Server Error
Something broke on the server. Never leak stack traces.
502 Bad Gateway
An upstream service returned something invalid.
503 Service Unavailable
Temporarily down or overloaded. Pair with Retry-After.
504 Gateway Timeout
An upstream service did not answer in time.About the http status code reference
Most APIs use four codes and lean on 400 for everything that goes wrong. That loses information the client could act on: 401 means authenticate, 403 means do not bother retrying, 409 means resolve a conflict, 422 means fix the values.
Each entry here says when the code applies and, where it matters, when people reach for it incorrectly.
How to use it
- 1Filter by class, or search by code, name or description.
- 2Read when each applies.
- 3Match the response to what the client should do next.
Questions
What is the difference between 401 and 403?
401 means no valid credentials were supplied, so authenticating may help. 403 means you are authenticated but not allowed, so retrying with the same identity will not help.
Should validation failures return 400 or 422?
400 means the request itself is malformed. 422 means it parsed fine but the values failed validation. 422 is more precise for form errors.
When should I use 410 instead of 404?
410 says the resource existed and was deliberately removed. It is a stronger signal, and search engines drop a 410 page faster than a 404.