Edit

Share via

HTTP support in .NET

  • Article

Hypertext Transfer Protocol (or HTTP) is a protocol for requesting resources from a web server. The System.Net.Http.HttpClient class exposes the ability to send HTTP requests and receive HTTP responses from a resource identified by a URI. Many types of resources are available on the web, and HTTP defines a set of request methods for accessing these resources.

HTTP request methods

The request methods are differentiated via several factors, first by their verb but also by the following characteristics:

  • A request method is idempotent if it can be successfully processed multiple times without changing the result. For more information, see RFC 9110: 9.2.2. Idempotent Methods.
  • A request method is cacheable when its corresponding response can be stored for reuse. For more information, see RFC 9110: Section 9.2.3. Methods and Caching.
  • A request method is considered a safe method if it doesn't modify the state of a resource. All safe methods are also idempotent, but not all idempotent methods are considered safe. For more information, see RFC 9110: Section 9.2.1. Safe Methods.
HTTP method Is idempotent Is cacheable Is safe
GET ✔️ Yes ✔️ Yes ✔️ Yes
POST ❌ No ⚠️ †Rarely ❌ No
PUT ✔️ Yes ❌ No ❌ No
PATCH ❌ No ❌ No ❌ No
DELETE ✔️ Yes ❌ No ❌ No
HEAD ✔️ Yes ✔️ Yes ✔️ Yes
OPTIONS ✔️ Yes ❌ No ✔️ Yes
TRACE ✔️ Yes ❌ No ✔️ Yes
CONNECT ❌ No ❌ No ❌ No

†The POST method is only cacheable when the appropriate Cache-Control or Expires response headers are present. This is very uncommon in practice.

HTTP status codes

.NET provides comprehensive support for the HTTP protocol, which accounts for most internet traffic, with the HttpClient. For more information, see Make HTTP requests with the HttpClient class. Applications receive HTTP protocol errors by catching an HttpRequestException. HTTP status codes are either reported in HttpResponseMessage with the HttpResponseMessage.StatusCode or in HttpRequestException with the HttpRequestException.StatusCode in case the called method doesn't return a response message. For more information about error handling, see HTTP error handling, and for more information about status codes, see RFC 9110, HTTP Semantics: Status Codes.

Informational status codes

The informational status codes reflect an interim response. Most of the interim responses, for example HttpStatusCode.Continue, are handled internally with HttpClient and are never surfaced to the user.

HTTP status code HttpStatusCode
100 HttpStatusCode.Continue
101 HttpStatusCode.SwitchingProtocols
102 HttpStatusCode.Processing
103 HttpStatusCode.EarlyHints

Successful status codes

The successful status codes indicate that the client's request was successfully received, understood, and accepted.

HTTP status code HttpStatusCode
200 HttpStatusCode.OK
201 HttpStatusCode.Created
202 HttpStatusCode.Accepted
203 HttpStatusCode.NonAuthoritativeInformation
204 HttpStatusCode.NoContent
205 HttpStatusCode.ResetContent
206 HttpStatusCode.PartialContent
207 HttpStatusCode.MultiStatus
208 HttpStatusCode.AlreadyReported
226 HttpStatusCode.IMUsed

Redirection status codes

Redirection status codes require the user agent to take action to fulfill the request. Automatic redirection is turned on by default, it can be changed with HttpClientHandler.AllowAutoRedirect or SocketsHttpHandler.AllowAutoRedirect.

HTTP status code HttpStatusCode
300 HttpStatusCode.MultipleChoices or HttpStatusCode.Ambiguous
301 HttpStatusCode.MovedPermanently or HttpStatusCode.Moved
302 HttpStatusCode.Found or HttpStatusCode.Redirect
303 HttpStatusCode.SeeOther or HttpStatusCode.RedirectMethod
304 HttpStatusCode.NotModified
305 HttpStatusCode.UseProxy
306 HttpStatusCode.Unused
307 HttpStatusCode.TemporaryRedirect or HttpStatusCode.RedirectKeepVerb
308 HttpStatusCode.PermanentRedirect

Client error status codes

The client error status codes indicate that the client's request was invalid.

HTTP status code HttpStatusCode
400 HttpStatusCode.BadRequest
401 HttpStatusCode.Unauthorized
402 HttpStatusCode.PaymentRequired
403 HttpStatusCode.Forbidden
404 HttpStatusCode.NotFound
405 HttpStatusCode.MethodNotAllowed
406 HttpStatusCode.NotAcceptable
407 HttpStatusCode.ProxyAuthenticationRequired
408 HttpStatusCode.RequestTimeout
409 HttpStatusCode.Conflict
410 HttpStatusCode.Gone
411 HttpStatusCode.LengthRequired
412 HttpStatusCode.PreconditionFailed
413 HttpStatusCode.RequestEntityTooLarge
414 HttpStatusCode.RequestUriTooLong
415 HttpStatusCode.UnsupportedMediaType
416 HttpStatusCode.RequestedRangeNotSatisfiable
417 HttpStatusCode.ExpectationFailed
418 I'm a teapot 🫖
421 HttpStatusCode.MisdirectedRequest
422 HttpStatusCode.UnprocessableEntity
423 HttpStatusCode.Locked
424 HttpStatusCode.FailedDependency
426 HttpStatusCode.UpgradeRequired
428 HttpStatusCode.PreconditionRequired
429 HttpStatusCode.TooManyRequests
431 HttpStatusCode.RequestHeaderFieldsTooLarge
451 HttpStatusCode.UnavailableForLegalReasons

Server error status codes

The server error status codes indicate that the server encountered an unexpected condition that prevented it from fulfilling the request.

HTTP status code HttpStatusCode
500 HttpStatusCode.InternalServerError
501 HttpStatusCode.NotImplemented
502 HttpStatusCode.BadGateway
503 HttpStatusCode.ServiceUnavailable
504 HttpStatusCode.GatewayTimeout
505 HttpStatusCode.HttpVersionNotSupported
506 HttpStatusCode.VariantAlsoNegotiates
507 HttpStatusCode.InsufficientStorage
508 HttpStatusCode.LoopDetected
510 HttpStatusCode.NotExtended
511 HttpStatusCode.NetworkAuthenticationRequired

See also