HTTP Status Codes and Headers
By the Syncfusion DevTutorials team · Last updated
Every status code and header used in the course, with what it means, when to send it and a one-line C# and Hono example.
The Status Code and Header Reference is a quick guide to the HTTP status codes and headers used throughout this course. It explains what each one means, when to use it, and how it helps clients and servers communicate clearly. A status code is the three-digit number that appears at the beginning of every HTTP response. It tells the client whether the request succeeded, failed, or needs a different action.
An HTTP header is additional information sent with a request or response. Headers help clients and servers exchange important details such as content type, authentication information, caching rules, and version details.
Understanding Status Code Families
The first digit of a status code tells you its family:
- 2xx → The request succeeded.
- 3xx → The client should use another location or a cached copy.
- 4xx → The client sent something wrong and must change the request.
- 5xx → The server failed while processing the request.
Ask yourself one simple question: can the client fix this by changing the request? If the answer is yes, return a 4xx status code. If the answer is no, return a 5xx status code.
Quick Reference
| Code | Name | Meaning |
|---|---|---|
200 | OK | The request succeeded and the response contains data |
201 | Created | A new resource was created |
202 | Accepted | The request was accepted and will be processed later |
204 | No Content | The request succeeded and there is nothing to return |
304 | Not Modified | The cached copy is still valid |
400 | Bad Request | The request is invalid or cannot be understood |
401 | Unauthorized | Authentication is missing or invalid |
403 | Forbidden | The user is known but is not allowed to perform this action |
404 | Not Found | The requested resource does not exist |
405 | Method Not Allowed | The URL exists but does not support this HTTP method |
409 | Conflict | The request conflicts with the current state |
415 | Unsupported Media Type | The server cannot process the request body format |
422 | Unprocessable Content | The request format is valid, but the data breaks business rules |
429 | Too Many Requests | The client has sent too many requests |
500 | Internal Server Error | An unexpected server error occurred |
502 | Bad Gateway | A server behind the gateway returned an invalid response |
503 | Service Unavailable | The service is temporarily unavailable |
504 | Gateway Timeout | A server behind the gateway took too long to respond |
2xx - Success Responses
These status codes mean the request was processed successfully.
200 OK
Use when the request succeeds and returns data. Common uses are reading data with GET, and returning an updated resource after PUT or PATCH.
201 Created
Use when a new resource is created. The response should include the created resource and a Location header that points to the new resource.
202 Accepted
Use when the request is accepted but processing has not finished yet. Common uses are long-running jobs, report generation, and background processing.
204 No Content
Use when the request succeeds but there is no data to return. Common uses are a successful DELETE, and updates that do not need to return data.
3xx - Redirection and Caching
These status codes tell the client to use another location or a cached copy.
304 Not Modified
Use when the resource has not changed since the last request of the client. The server sends no response body, and the client uses its cached version instead. The benefits are faster responses and reduced network usage.
4xx - Client Errors
These status codes mean the client must fix something before trying again.
400 Bad Request
The server cannot understand the request. Examples are invalid JSON, missing required fields, and invalid data types.
401 Unauthorized
The request does not contain valid authentication information. Examples are a missing token, an expired token, and an invalid token.
403 Forbidden
The user is authenticated but does not have permission. Examples are a customer who tries to access an admin endpoint, and a user who attempts an operation that they are not allowed to perform.
404 Not Found
The requested resource does not exist. Examples are an invalid order id, a missing menu item, and an unknown customer.
405 Method Not Allowed
The URL exists, but the HTTP method is not supported. Example: DELETE /menu when only GET is supported. The response should include an Allow header that lists the supported methods.
409 Conflict
The request is valid, but it conflicts with the current state. Examples are cancelling an order that is already delivered, and reusing an Idempotency-Key with different data.
415 Unsupported Media Type
The request body format is not supported. The most common cause: the Content-Type header is missing or incorrect.
422 Unprocessable Content
The request format is correct, but the values are not valid. Examples are a quantity of zero, a product that is not available, and a required value that is empty. Return all validation errors, so the user can fix everything at once.
Some APIs return 400 Bad Request for validation errors instead of 422 Unprocessable Content. Both ways are common. Choose one way, and use it everywhere in the API.
429 Too Many Requests
The client has exceeded the allowed request limit. The response should include a Retry-After header, so the client knows when it can try again.
5xx - Server Errors
These status codes mean the problem is on the server.
500 Internal Server Error
An unexpected error occurred inside the application. Examples are application bugs and unhandled exceptions.
502 Bad Gateway
A gateway or proxy received an invalid response from another service.
503 Service Unavailable
The service is temporarily unavailable. Examples are maintenance, high server load, and startup or shutdown.
504 Gateway Timeout
A gateway waited too long for another service to respond. A retry may be safe if the request is idempotent or uses an Idempotency-Key.
Never return 200 OK when an operation has failed. Clients, browsers, monitoring systems and caches trust the status code first. If a failure is hidden inside a 200 response, every system will treat it as a success.
Which Status Codes Can Be Retried?
| Code | Retry? |
|---|---|
400, 401, 403, 404, 405, 409, 415, 422 | No. Fix the request first |
429 | Yes. Wait for the time specified in Retry-After |
502, 503, 504 | Yes. Retry with backoff if safe |
500 | Sometimes. If it is a temporary issue, one retry may succeed |
Request Headers
Request headers are sent by the client.
| Header | Purpose |
|---|---|
Content-Type | Specifies the format of the request body |
Accept | Specifies the response format the client wants |
Authorization | Sends authentication credentials |
X-Api-Key | Sends an API key |
Idempotency-Key | Prevents duplicate processing of retried requests |
If-None-Match | Requests data only if it has changed |
X-Api-Version | Chooses an API version |
X-Correlation-Id | Helps track a request across logs |
traceparent | Carries distributed tracing information |
Origin | Identifies the website making the request |
User-Agent | Identifies the calling application |
Response Headers
Response headers are sent by the server.
| Header | Purpose |
|---|---|
Content-Type | Specifies the format of the response body |
Location | Provides the URL of a newly created resource |
Allow | Lists supported HTTP methods |
WWW-Authenticate | Explains how to authenticate |
ETag | Identifies a specific version of a resource |
Cache-Control | Defines caching rules |
Vary | Identifies which request headers change the response |
Retry-After | Tells the client when it may try again |
RateLimit-Limit | Maximum requests allowed |
RateLimit-Remaining | Remaining requests available |
RateLimit-Reset | Time until rate limits reset |
Deprecation | Indicates that a feature is being deprecated |
Sunset | Indicates when a feature will be removed |
X-Correlation-Id | Helps support teams find related logs |
Access-Control-Allow-Origin | Allows a website to access the response |
Do not put internal system information in headers. Never trust a value such as X-User-Id when it comes directly from an outside client. Always get the user from trusted authentication data, such as a token.