Error handling with the HTTP connector

The HTTP connector surfaces enriched error data that helps you identify, manage, and resolve issues when a request fails. It displays the HTTP status, a standardized error message, and structured response details such as headers and body. These details improve clarity and support automation. This feature currently applies to the HTTP connector.

How to view the error message

The connector raises an error when the Send request action receives a non-2xx response.

The job report's Error tab displays the following:

• A structured error message
• HTTP response status
• Response headers
• Response body (when applicable)

Each value appears in a dedicated field. You can use these in Monitor blocks, logs, or other error-handling logic.

HTTP connector error datapills for Monitor and On error blocks.

Error structure

The HTTP connector includes the following fields in job errors:

Field	Description
error_type_id	Stable identifier for the error type. For example: err.http.response.client_error.not_found.
error_type	Display name based on HTTP status. For example: 404 Not Found.
error_id	Unique identifier for the error instance.
error_message	High-level message. For example, HTTP 500 error.
http_response.code	Numeric HTTP status code. For example: 404.
http_response.status_text	HTTP status text. For example: Not Found.
http_response.headers	HTTP response headers.
http_response.body	HTTP response body as a string.

HTTP error type IDs

The error_type_id field for the HTTP connector follows a structured format based on standard HTTP status code classes. You can use these patterns to identify and handle categories of HTTP errors in recipes:

HTTP status class	Example error_type_id prefix	Description
3xx	err.http.response.redirection	Redirection responses
4xx	err.http.response.client_error	Client-side errors, such as 404 or 401
5xx	err.http.response.server_error	Server-side errors, such as 500 or 503

Use these prefixes in Monitor or On error blocks to group and handle related HTTP failures. For example, you can check if error_type_id starts with err.http.response.client_error to catch all client-side issues.

Structured HTTP error output

The HTTP connector returns a structured error object you can use for debugging, filtering, and automation. This object includes fields such as the HTTP status code, response body, headers, and a machine-readable error type ID. For example:

{
  "error_type_id": "err.http.response.client_error.not_found",
  "error_type": "Not Found",
  "error_id": "ad6a...b3c",
  "error_message": "HTTP 404 error",
  "http_response": {
    "code": 404,
    "status_text": "Not Found",
    "body": "{\"error\": \"Resource not found\"}",
    "headers": {
      "Content-Type": "application/json"
    }
  }
}

You can access this structured error data through the following:

• Job reports
• Monitor blocks (error datapills)
• On error blocks (error datapills)

Workato recommends using error_type_id for automation. This field is stable and supports reliable programmatic checks.

Best practices for error handling

Use error_type_id and http_response fields in Monitor or On error blocks to build reliable recipes:

• Catch and handle specific errors using error_type_id
• Retry requests based on HTTP status codes or response headers
• Send structured error data to logs or alerting systems

These fields eliminate the need for string parsing or fragile pattern matching.