| Range | Category | What it means |
|---|---|---|
1xx | Informational | Request received; server is continuing the process. Rarely seen by clients. |
2xx | Success | The request was received, understood, and accepted. Your happy path. |
3xx | Redirection | Further action is needed to complete the request — usually a redirect to another URL. |
4xx | Client Error | The request contains bad syntax or cannot be fulfilled. The client needs to fix something. |
5xx | Server Error | The server failed to fulfil a valid request. Something went wrong on your side. |
| Code | Name | When to use / what it means |
|---|---|---|
200 | OK | Standard success. Return with a response body for GET/POST. |
201 | Created | A new resource was created (e.g. POST to create a user). Include a Location header. |
204 | No Content | Success, but nothing to return — common for DELETE or PUT. |
301 | Moved Permanently | URL has changed forever. Browsers and crawlers update their records. Use for SEO-friendly redirects. |
304 | Not Modified | Cached version is still valid. Browser uses its cached copy — fast and bandwidth-efficient. |
400 | Bad Request | The client sent invalid data. Return a clear error message explaining what's wrong. |
401 | Unauthorized | Missing or invalid authentication. The client can try again with credentials. |
403 | Forbidden | Authenticated but not allowed. Don't reveal whether the resource exists. |
404 | Not Found | Resource doesn't exist. Can also be used deliberately to avoid revealing restricted resources. |
429 | Too Many Requests | Rate limiting. Include a Retry-After header so clients know when to retry. |
500 | Internal Server Error | Unhandled exception. Log it, alert on it, and return a generic message to the client. |
503 | Service Unavailable | Down for maintenance or overloaded. Use with Retry-After for planned downtime. |