ESP32 HTTPClient Library – HTTP Status Codes and Error Codes

Home / References / ESP32 Library / HTTPClient

The GET, POST, PUT methods return an integer representing either an HTTP status code (indicating the server’s response) or an error code (indicating a client-side issue). Below are all possible values as defined in the ESP32 HTTPClient Library:

HTTP Status Codes (Positive Values):

• 100 (HTTP_CODE_CONTINUE): Server has received the request headers and the client should proceed.
• 101 (HTTP_CODE_SWITCHING_PROTOCOLS): Server is switching protocols as requested.
• 102 (HTTP_CODE_PROCESSING): Server is processing the request but not yet complete.
• 200 (HTTP_CODE_OK): Request successful; response body is available.
• 201 (HTTP_CODE_CREATED): Resource was created successfully.
• 202 (HTTP_CODE_ACCEPTED): Request accepted for processing, but not completed.
• 203 (HTTP_CODE_NON_AUTHORITATIVE_INFORMATION): Returned metadata is not definitive.
• 204 (HTTP_CODE_NO_CONTENT): Request successful, but no content returned.
• 205 (HTTP_CODE_RESET_CONTENT): Client should reset the document view.
• 206 (HTTP_CODE_PARTIAL_CONTENT): Partial content returned, typically for range requests.
• 207 (HTTP_CODE_MULTI_STATUS): Multiple status codes in the response (WebDAV).
• 208 (HTTP_CODE_ALREADY_REPORTED): Results already reported (WebDAV).
• 226 (HTTP_CODE_IM_USED): Server has fulfilled a request for the resource with an IM.
• 300 (HTTP_CODE_MULTIPLE_CHOICES): Multiple options for the resource.
• 301 (HTTP_CODE_MOVED_PERMANENTLY): Resource has moved permanently.
• 302 (HTTP_CODE_FOUND): Resource temporarily moved.
• 303 (HTTP_CODE_SEE_OTHER): Response can be found under a different URI.
• 304 (HTTP_CODE_NOT_MODIFIED): Resource not modified since last request.
• 305 (HTTP_CODE_USE_PROXY): Resource must be accessed through a proxy.
• 307 (HTTP_CODE_TEMPORARY_REDIRECT): Temporary redirect to another URI.
• 308 (HTTP_CODE_PERMANENT_REDIRECT): Permanent redirect to another URI.
• 400 (HTTP_CODE_BAD_REQUEST): Server rejected the request due to invalid syntax.
• 401 (HTTP_CODE_UNAUTHORIZED): Authentication required.
• 402 (HTTP_CODE_PAYMENT_REQUIRED): Payment required to access the resource.
• 403 (HTTP_CODE_FORBIDDEN): Access to the resource is denied.
• 404 (HTTP_CODE_NOT_FOUND): Requested resource was not found.
• 405 (HTTP_CODE_METHOD_NOT_ALLOWED): HTTP method not allowed for this resource.
• 406 (HTTP_CODE_NOT_ACCEPTABLE): Resource not available in an acceptable format.
• 407 (HTTP_CODE_PROXY_AUTHENTICATION_REQUIRED): Proxy authentication required.
• 408 (HTTP_CODE_REQUEST_TIMEOUT): Server timed out waiting for the request.
• 409 (HTTP_CODE_CONFLICT): Request conflicts with the current state of the resource.
• 410 (HTTP_CODE_GONE): Resource is no longer available.
• 411 (HTTP_CODE_LENGTH_REQUIRED): Content-Length header required.
• 412 (HTTP_CODE_PRECONDITION_FAILED): Precondition in request headers failed.
• 413 (HTTP_CODE_PAYLOAD_TOO_LARGE): Request payload exceeds server limits.
• 414 (HTTP_CODE_URI_TOO_LONG): Request URI exceeds server limits.
• 415 (HTTP_CODE_UNSUPPORTED_MEDIA_TYPE): Media type not supported by the server.
• 416 (HTTP_CODE_RANGE_NOT_SATISFIABLE): Requested range not satisfiable.
• 417 (HTTP_CODE_EXPECTATION_FAILED): Expectation in request headers not met.
• 421 (HTTP_CODE_MISDIRECTED_REQUEST): Request sent to a server unable to respond.
• 422 (HTTP_CODE_UNPROCESSABLE_ENTITY): Request well-formed but semantically incorrect.
• 423 (HTTP_CODE_LOCKED): Resource is locked (WebDAV).
• 424 (HTTP_CODE_FAILED_DEPENDENCY): Request failed due to a prior dependency (WebDAV).
• 426 (HTTP_CODE_UPGRADE_REQUIRED): Client must upgrade to a different protocol.
• 428 (HTTP_CODE_PRECONDITION_REQUIRED): Precondition required in the request.
• 429 (HTTP_CODE_TOO_MANY_REQUESTS): Rate limit exceeded.
• 431 (HTTP_CODE_REQUEST_HEADER_FIELDS_TOO_LARGE): Request headers exceed server limits.
• 500 (HTTP_CODE_INTERNAL_SERVER_ERROR): Server encountered an unexpected error.
• 501 (HTTP_CODE_NOT_IMPLEMENTED): Server does not support the requested functionality.
• 502 (HTTP_CODE_BAD_GATEWAY): Invalid response from an upstream server.
• 503 (HTTP_CODE_SERVICE_UNAVAILABLE): Server temporarily unavailable.
• 504 (HTTP_CODE_GATEWAY_TIMEOUT): Upstream server failed to respond in time.
• 505 (HTTP_CODE_HTTP_VERSION_NOT_SUPPORTED): HTTP version not supported.
• 506 (HTTP_CODE_VARIANT_ALSO_NEGOTIATES): Server configuration error in negotiation.
• 507 (HTTP_CODE_INSUFFICIENT_STORAGE): Insufficient storage on the server (WebDAV).
• 508 (HTTP_CODE_LOOP_DETECTED): Infinite loop detected (WebDAV).
• 510 (HTTP_CODE_NOT_EXTENDED): Further extensions required for the request.
• 511 (HTTP_CODE_NETWORK_AUTHENTICATION_REQUIRED): Network authentication required.

Error Codes (Negative Values):

• -1 (HTTPC_ERROR_CONNECTION_REFUSED): Connection to the server was refused.
• -2 (HTTPC_ERROR_SEND_HEADER_FAILED): Failed to send HTTP headers.
• -3 (HTTPC_ERROR_SEND_PAYLOAD_FAILED): Failed to send payload (not typically applicable to GET).
• -4 (HTTPC_ERROR_NOT_CONNECTED): Not connected to the server.
• -5 (HTTPC_ERROR_CONNECTION_LOST): Connection to the server was lost.
• -6 (HTTPC_ERROR_NO_STREAM): No stream available to read the response.
• -7 (HTTPC_ERROR_NO_HTTP_SERVER): Server did not respond as an HTTP server.
• -8 (HTTPC_ERROR_TOO_LESS_RAM): Insufficient RAM to complete the operation.
• -9 (HTTPC_ERROR_ENCODING): Transfer encoding error (e.g., unsupported chunked encoding).
• -10 (HTTPC_ERROR_STREAM_WRITE): Error writing to the stream.
• -11 (HTTPC_ERROR_READ_TIMEOUT): Read operation timed out.

These return values enable detailed handling of both server responses and client-side errors, making your IoT projects more reliable and debuggable. Note that while this list covers common HTTP codes, the server might return other valid HTTP status codes depending on its implementation.