Up to date

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

HTTPRequest

Inherits: Node < Object

A node with the ability to send HTTP(S) requests.

Description

A node with the ability to send HTTP requests. Uses HTTPClient internally.

Can be used to make HTTP requests, i.e. download or upload files or web content via HTTP.

Warning: See the notes and warnings on HTTPClient for limitations, especially regarding TLS security.

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.

Example of contacting a REST API and printing one of its returned fields:

func _ready():
    # Create an HTTP request node and connect its completion signal.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Perform a GET request. The URL below returns JSON as of writing.
    var error = http_request.request("https://httpbin.org/get")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

    # Perform a POST request. The URL below returns JSON as of writing.
    # Note: Don't make simultaneous requests using a single HTTPRequest node.
    # The snippet below is provided for reference only.
    var body = JSON.new().stringify({"name": "Godette"})
    error = http_request.request("https://httpbin.org/post", [], HTTPClient.METHOD_POST, body)
    if error != OK:
        push_error("An error occurred in the HTTP request.")

# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
    var json = JSON.new()
    json.parse(body.get_string_from_utf8())
    var response = json.get_data()

    # Will print the user agent string used by the HTTPRequest node (as recognized by httpbin.org).
    print(response.headers["User-Agent"])

Example of loading and displaying an image using HTTPRequest:

func _ready():
    # Create an HTTP request node and connect its completion signal.
    var http_request = HTTPRequest.new()
    add_child(http_request)
    http_request.request_completed.connect(self._http_request_completed)

    # Perform the HTTP request. The URL below returns a PNG image as of writing.
    var error = http_request.request("https://via.placeholder.com/512")
    if error != OK:
        push_error("An error occurred in the HTTP request.")

# Called when the HTTP request is completed.
func _http_request_completed(result, response_code, headers, body):
    if result != HTTPRequest.RESULT_SUCCESS:
        push_error("Image couldn't be downloaded. Try a different image.")

    var image = Image.new()
    var error = image.load_png_from_buffer(body)
    if error != OK:
        push_error("Couldn't load the image.")

    var texture = ImageTexture.create_from_image(image)

    # Display the image in a TextureRect node.
    var texture_rect = TextureRect.new()
    add_child(texture_rect)
    texture_rect.texture = texture

Gzipped response bodies: HTTPRequest will automatically handle decompression of response bodies. A Accept-Encoding header will be automatically added to each of your requests, unless one is already specified. Any response with a Content-Encoding: gzip header will automatically be decompressed and delivered to you as uncompressed bytes.

Tutorials

Properties

bool

accept_gzip

true

int

body_size_limit

-1

int

download_chunk_size

65536

String

download_file

""

int

max_redirects

8

float

timeout

0.0

bool

use_threads

false

Methods

void

cancel_request ( )

int

get_body_size ( ) const

int

get_downloaded_bytes ( ) const

Status

get_http_client_status ( ) const

Error

request ( String url, PackedStringArray custom_headers=PackedStringArray(), Method method=0, String request_data="" )

Error

request_raw ( String url, PackedStringArray custom_headers=PackedStringArray(), Method method=0, PackedByteArray request_data_raw=PackedByteArray() )

void

set_http_proxy ( String host, int port )

void

set_https_proxy ( String host, int port )

void

set_tls_options ( TLSOptions client_options )


Signals

request_completed ( int result, int response_code, PackedStringArray headers, PackedByteArray body )

Emitted when a request is completed.


Enumerations

enum Result:

Result RESULT_SUCCESS = 0

Request successful.

Result RESULT_CHUNKED_BODY_SIZE_MISMATCH = 1

Result RESULT_CANT_CONNECT = 2

Request failed while connecting.

Result RESULT_CANT_RESOLVE = 3

Request failed while resolving.

Result RESULT_CONNECTION_ERROR = 4

Request failed due to connection (read/write) error.

Result RESULT_TLS_HANDSHAKE_ERROR = 5

Request failed on TLS handshake.

Result RESULT_NO_RESPONSE = 6

Request does not have a response (yet).

Result RESULT_BODY_SIZE_LIMIT_EXCEEDED = 7

Request exceeded its maximum size limit, see body_size_limit.

Result RESULT_BODY_DECOMPRESS_FAILED = 8

Result RESULT_REQUEST_FAILED = 9

Request failed (currently unused).

Result RESULT_DOWNLOAD_FILE_CANT_OPEN = 10

HTTPRequest couldn't open the download file.

Result RESULT_DOWNLOAD_FILE_WRITE_ERROR = 11

HTTPRequest couldn't write to the download file.

Result RESULT_REDIRECT_LIMIT_REACHED = 12

Request reached its maximum redirect limit, see max_redirects.

Result RESULT_TIMEOUT = 13

Request failed due to a timeout. If you expect requests to take a long time, try increasing the value of timeout or setting it to 0.0 to remove the timeout completely.


Property Descriptions

bool accept_gzip = true

  • void set_accept_gzip ( bool value )

  • bool is_accepting_gzip ( )

If true, this header will be added to each request: Accept-Encoding: gzip, deflate telling servers that it's okay to compress response bodies.

Any Response body declaring a Content-Encoding of either gzip or