Up to date

This page is up to date for Godot 4.2. If you still find outdated information, please open an issue.

HTTPClient¶

Low-level hyper-text transfer protocol client.

Description¶

Hyper-text transfer protocol client (sometimes called "User Agent"). Used to make HTTP requests to download web content, upload files and other data or to communicate with various services, among other use cases.

See the HTTPRequest node for a higher-level alternative.

Note: This client only needs to connect to a host once (see connect_to_host) to send multiple requests. Because of this, methods that take URLs usually take just the part after the host instead of the full URL, as the client is already connected to a host. See request for a full example and to get started.

A HTTPClient should be reused between multiple requests or to connect to different hosts instead of creating one client per request. Supports Transport Layer Security (TLS), including server certificate verification. HTTP status codes in the 2xx range indicate success, 3xx redirection (i.e. "try again, but over here"), 4xx something was wrong with the request, and 5xx something went wrong on the server's side.

For more information on HTTP, see MDN's documentation on HTTP (or read RFC 2616 to get it straight from the source).

Note: When exporting to Android, make sure to enable the INTERNET permission in the Android export preset before exporting the project or using one-click deploy. Otherwise, network communication of any kind will be blocked by Android.

Note: It's recommended to use transport encryption (TLS) and to avoid sending sensitive information (such as login credentials) in HTTP GET URL parameters. Consider using HTTP POST requests or HTTP headers for such information instead.

Note: When performing HTTP requests from a project exported to Web, keep in mind the remote server may not allow requests from foreign origins due to CORS. If you host the server in question, you should modify its backend to allow requests from foreign origins by adding the Access-Control-Allow-Origin: * HTTP header.

Note: TLS support is currently limited to TLS 1.0, TLS 1.1, and TLS 1.2. Attempting to connect to a TLS 1.3-only server will return an error.

Warning: TLS certificate revocation and certificate pinning are currently not supported. Revoked certificates are accepted as long as they are otherwise valid. If this is a concern, you may want to use automatically managed certificates with a short validity period.

Tutorials¶

Properties¶

bool	blocking_mode_enabled	`false`
StreamPeer	connection
int	read_chunk_size	`65536`

Methods¶

void	close ( )
Error	connect_to_host ( String host, int port=-1, TLSOptions tls_options=null )
int	get_response_body_length ( ) const
int	get_response_code ( ) const
PackedStringArray	get_response_headers ( )
Dictionary	get_response_headers_as_dictionary ( )
Status	get_status ( ) const
bool	has_response ( ) const
bool	is_response_chunked ( ) const
Error	poll ( )
String	query_string_from_dict ( Dictionary fields )
PackedByteArray	read_response_body_chunk ( )
Error	request ( Method method, String url, PackedStringArray headers, String body="" )
Error	request_raw ( Method method, String url, PackedStringArray headers, PackedByteArray body )
void	set_http_proxy ( String host, int port )
void	set_https_proxy ( String host, int port )

Enumerations¶

enum Method:

Method METHOD_GET = 0

HTTP GET method. The GET method requests a representation of the specified resource. Requests using GET should only retrieve data.

Method METHOD_HEAD = 1

HTTP HEAD method. The HEAD method asks for a response identical to that of a GET request, but without the response body. This is useful to request metadata like HTTP headers or to check if a resource exists.

Method METHOD_POST = 2

HTTP POST method. The POST method is used to submit an entity to the specified resource, often causing a change in state or side effects on the server. This is often used for forms and submitting data or uploading files.

Method METHOD_PUT = 3

HTTP PUT method. The PUT method asks to replace all current representations of the target resource with the request payload. (You can think of POST as "create or update" and PUT as "update", although many services tend to not make a clear distinction or change their meaning).

Method METHOD_DELETE = 4

HTTP DELETE method. The DELETE method requests to delete the specified resource.

Method METHOD_OPTIONS = 5

HTTP OPTIONS method. The OPTIONS method asks for a description of the communication options for the target resource. Rarely used.

Method METHOD_TRACE = 6

HTTP TRACE method. The TRACE method performs a message loop-back test along the path to the target resource. Returns the entire HTTP request received in the response body. Rarely used.

Method METHOD_CONNECT = 7

HTTP CONNECT method. The CONNECT method establishes a tunnel to the server identified by the target resource. Rarely used.

Method METHOD_PATCH = 8

HTTP PATCH method. The PATCH method is used to apply partial modifications to a resource.

Method METHOD_MAX = 9

Represents the size of the Method enum.

enum Status:

Status STATUS_DISCONNECTED = 0

Status: Disconnected from the server.

Status STATUS_RESOLVING = 1

Status: Currently resolving the hostname for the given URL into an IP.

Status STATUS_CANT_RESOLVE = 2

Status: DNS failure: Can't resolve the hostname for the given URL.

Status STATUS_CONNECTING = 3

Status: Currently connecting to server.

Status STATUS_CANT_CONNECT = 4

Status: Can't connect to the server.

Status STATUS_CONNECTED = 5

Status: Connection established.

Status STATUS_REQUESTING = 6

Status: Currently sending request.

Status STATUS_BODY = 7

Status: HTTP body received.

Status STATUS_CONNECTION_ERROR = 8

Status: Error in HTTP connection.

Status STATUS_TLS_HANDSHAKE_ERROR = 9

Status: Error in TLS handshake.

enum ResponseCode:

ResponseCode RESPONSE_CONTINUE = 100

HTTP status code 100 Continue. Interim response that indicates everything so far is OK and that the client should continue with the request (or ignore this status if already finished).

ResponseCode RESPONSE_SWITCHING_PROTOCOLS = 101

HTTP status code 101 Switching Protocol. Sent in response to an Upgrade request header by the client. Indicates the protocol the server is switching to.

ResponseCode RESPONSE_PROCESSING = 102

HTTP status code 102 Processing (WebDAV). Indicates that the server has received and is processing the request, but no response is available yet.

ResponseCode RESPONSE_OK = 200

HTTP status code 200 OK. The request has succeeded. Default response for successful requests. Meaning varies depending on the request. GET: The resource has been fetched and is transmitted in the message body. HEAD: The entity headers are in the message body. POST: The resource describing the result of the action is transmitted in the message body. TRACE: The message body contains the request message as received by the server.

ResponseCode RESPONSE_CREATED = 201

HTTP status code 201 Created. The request has succeeded and a new resource has been created as a result of it. This is typically the response sent after a PUT request.

ResponseCode RESPONSE_ACCEPTED = 202

HTTP status code 202 Accepted. The request has been received but not yet acted upon. It is non-committal, meaning that there is no way in HTTP to later send an asynchronous response indicating the outcome of processing the request. It is intended for cases where another process or server handles the request, or for batch processing.

ResponseCode RESPONSE_NON_AUTHORITATIVE_INFORMATION = 203

HTTP status code 203 Non-Authoritative Information. This response code means returned meta-information set is not exact set as available from the origin server, but collected from a local or a third party copy. Except this condition, 200 OK response should be preferred instead of this response.

ResponseCode RESPONSE_NO_CONTENT = 204

HTTP status code 204 No Content. There is no content to send for this request, but the headers may be useful. The user-agent may update its cached headers for this resource with the new ones.

ResponseCode RESPONSE_RESET_CONTENT = 205

HTTP status code 205 Reset Content. The server has fulfilled the request and desires that the client resets the "document view" that caused the request to be sent to its original state as received from the origin server.

ResponseCode RESPONSE_PARTIAL_CONTENT = 206

HTTP status code 206 Partial Content. This response code is used because of a range header sent by the client to separate download into multiple streams.

ResponseCode RESPONSE_MULTI_STATUS = 207

HTTP status code 207 Multi-Status (WebDAV). A Multi-Status response conveys information about multiple resources in situations where multiple status codes might be appropriate.

ResponseCode RESPONSE_ALREADY_REPORTED = 208

HTTP status code 208 Already Reported (WebDAV). Used inside a DAV: propstat response element to avoid enumerating the internal members of multiple bindings to the same collection repeatedly.

ResponseCode RESPONSE_IM_USED = 226

HTTP status code 226 IM Used (WebDAV). The server has fulfilled a GET request for the resource, and the response is a representation of the result of one or more instance-manipulations applied to the current instance.

ResponseCode RESPONSE_MULTIPLE_CHOICES = 300

HTTP status code 300 Multiple Choice. The request has more than one possible responses and there is no standardized way to choose one of the responses. User-agent or user should choose one of them.

ResponseCode RESPONSE_MOVED_PERMANENTLY = 301

HTTP status code 301 Moved Permanently. Redirection. This response code means the URI of requested resource has been changed. The new URI is usually included in the response.

ResponseCode RESPONSE_FOUND = 302

HTTP status code 302 Found. Temporary redirection. This response code means the URI of requested resource has been changed temporarily. New changes in the URI might be made in the future. Therefore, this same URI should be used by the client in future requests.

ResponseCode RESPONSE_SEE_OTHER = 303

HTTP status code 303 See Other. The server is redirecting the user agent to a different resource, as indicated by a URI in the Location header field, which is intended to provide an indirect response to the original request.

ResponseCode RESPONSE_NOT_MODIFIED = 304

HTTP status code 304 Not Modified. A conditional GET or HEAD request has been received and would have resulted in a 200 OK response if it were not for the fact that the condition evaluated to false.

ResponseCode RESPONSE_USE_PROXY = 305

Deprecated. HTTP status code 305 Use Proxy.