HTTP Status Code Reference

You got a 418 response and you are not sure if that is a real code or someone idea of a joke. (It is real. It means "I am a teapot." RFC 2324.) Look it up.

Browse by class or search by number. Each entry explains what triggers the code, whether to retry, and what to check first.

The five classes

The ones you will actually see

2xx

• 200 OK -- the request succeeded. The response body has what you asked for.
• 201 Created -- a new resource was created (usually from POST).
• 204 No Content -- success, but nothing to return. Common for DELETE.

3xx

• 301 Moved Permanently -- the resource has a new URL. Update your bookmarks.
• 302 Found -- temporary redirect. Keep the original URL.
• 304 Not Modified -- the cached version is still valid. No body sent.

4xx

• 400 Bad Request -- the server could not understand your request. Check your syntax.
• 401 Unauthorized -- you need to authenticate. Note: "Unauthorized" means "Unauthenticated" here. The naming is confusing.
• 403 Forbidden -- you are authenticated, but you do not have permission. Different from 401.
• 404 Not Found -- the resource does not exist. Or the server does not want you to know it exists.
• 408 Request Timeout -- the server gave up waiting for your request body.
• 429 Too Many Requests -- you are being rate-limited. Check the Retry-After header.

5xx

• 500 Internal Server Error -- generic catch-all. Something broke on the server.
• 502 Bad Gateway -- an upstream server returned an invalid response. Often a proxy or load balancer issue.
• 503 Service Unavailable -- the server is temporarily overloaded or under maintenance.
• 504 Gateway Timeout -- an upstream server did not respond in time.

Troubleshooting shortcut

When something breaks, check the class first before panicking about the specific code:

• 2xx -- worked. Move on.
• 4xx -- it is your request. Check your URL, headers, body, auth token.
• 5xx -- it is their server. Retry with backoff; if it persists, check their status page.