HTTP Request Nodes

Tyler Coleman-Latto
Tyler Coleman-Latto
  • Updated

Overview

The HTTP REST Request and HTTP SOAP Request nodes let you call external APIs and web services directly from a workflow. Use the REST node to integrate with modern JSON APIs, and the SOAP node to connect with legacy or enterprise systems that use XML-based web services. In this article, we'll be covering how each node works, what inputs to configure, how to use the response in downstream nodes, and how to handle errors.

 

Configure the HTTP REST Request node

The HTTP REST Request node sends an HTTP request to a URL you specify and returns the response as structured data your workflow can use.

Inputs

  • Method — the HTTP verb to use: GET, POST, PUT, PATCH, or DELETE
  • URL — the full URL to send the request to. This field is required; the node will fail with an error if it is blank.
  • Body — optional request body, as an object. Used for POST, PUT, and PATCH requests.
  • Headers — optional key-value pairs to include as request headers (for example, authorization tokens or content type overrides).
  • Params — optional key-value pairs appended as query string parameters.

Output

On success, the node returns an object with four fields:

  • data — the response body, parsed according to the response type you configured
  • headers — the response headers returned by the server
  • status — the HTTP status code (for example, 200, 201, 404)
  • statusText — the status message associated with the code (for example, OK, Not Found)

A 4xx or 5xx HTTP response from the target server causes the node to fail. Use an error link or the Error Handling tab to capture and handle these cases. The payload of the failing HTTP request will be present in the error.

 

Configure the HTTP SOAP Request node

The HTTP SOAP Request node sends a SOAP envelope to a web service endpoint. It handles the XML framing and required headers for you — you provide the service details and the message body.

Inputs

  • Namespace — the XML namespace of the SOAP service (for example, http://example.com/myservice)
  • Operation — the name of the SOAP operation to invoke (for example, GetAccountDetails)
  • URL — the WSDL or service endpoint URL
  • Message — optional XML body to include inside the SOAP envelope

The node automatically sets the Content-Type header to text/xml and constructs the SOAPAction header as namespace/operation. All SOAP requests use the POST method.

Output

The SOAP node returns the same output shape as the REST node: data, headers, status, and statusText. The data field contains the raw XML response body.

 

Handle HTTP errors

Both nodes fail the workflow step when an error occurs. The error code is available in the node's error output and can be inspected or routed using the Error Handling tab.

Here are some common error codes that may be returned:

  • HTTP_REQUEST_MISSING_URL — the URL field was empty
  • HTTP_REQUEST_INVALID_URL — the URL is malformed or not a valid HTTP/HTTPS address
  • HTTP_REQUEST_FAILED — the server returned a 4xx or 5xx response
  • HTTP_REQUEST_UNAUTHORIZED — the server returned a 401 Unauthorized response
  • HTTP_REQUEST_BAD_REQUEST — the server returned a 400 Bad Request response
  • HTTP_REQUEST_TIMEOUT — the request exceeded the configured timeout
  • HTTP_REQUEST_UNABLE_TO_REACH_HOST — the host was reachable but did not respond
  • HTTP_REQUEST_UNABLE_TO_RESOLVE_HOST — DNS resolution failed for the host
  • HTTP_REQUEST_CONNECTION_CLOSED — the connection was closed before a response was received
  • HTTP_REQUEST_CONNECTION_REFUSED — the host actively refused the connection
  • HTTP_REQUEST_REJECTED_CERTIFICATE — the server's TLS certificate was rejected
  • HTTP_REQUEST_CANCELED — the request was canceled before completing
  • HTTP_CLIENT_THROTTLE_ERROR — the request was rate-limited by gaiia's HTTP client
  • HTTP_REQUEST_GENERIC_ERROR — an unclassified network or request error occurred

To handle specific error codes, add an error link from the node and use a Condition Node to branch on the error code value. See Handling Node Failures for details on retry strategies, timeouts, and error links.

 

Common usage patterns

Make an authenticated API call

To call an API that requires authentication, set the Headers field using a function input and return the headers object from a TypeScript function. Store credentials as workflow secrets or input variables rather than hardcoding them in the node configuration.

Example function input for bearer token authentication:

({ secrets }) => ({ Authorization: `Bearer ${secrets.API_TOKEN}` })

Pass workflow data in the request

The Body and Params fields accept dynamic values using the output mapper. Reference outputs from upstream nodes to build the request payload from live workflow data.

Use the response in downstream nodes

The node output is available to all downstream nodes via the workflow state object. Reference the node by its slug to access its output — for example, if the REST node has the slug get-account, a downstream TypeScript function can access the response body with state.steps['get-account'].output.data.accountId.

 

Map error outputs

When an HTTP node fails, its error is available to the error mapper via the error object, which exposes error.code, error.message, and error.payload. Use the error mapper to extract and rename error fields so they're available to downstream nodes connected via an error link.

A common pattern is to map error.code to a named output and then use a Condition Node on the error link to branch on specific HTTP error codes — for example, routing HTTP_REQUEST_UNAUTHORIZED differently from HTTP_REQUEST_TIMEOUT.

For full configuration details, see Using the Error Mapper.

Related to

Was this article helpful?

Have more questions? Submit a request