Jump to

• Request
• Response

Create Event Subscription

post

/v1/besu/event-subscriptions

Creates a callback-based subscription for newHeads or filtered logs events, with optional block ranges, retry settings, OAuth, and TLS configuration. It returns the newly created subscription, including its ID and running status.

Request

There are no request parameters for this operation.

Supported Media Types

• application/json

Request Body - application/json ()

Root Schema : schema

Type: object

Request to create a Besu event subscription. Supports recoverable event types only: `newHeads` and `logs`. `logsFilter` is only valid when `type=logs`. `nonEmptyBlocksOnly` is only valid when `type=newHeads`.

Show Source

• callbackUrl(required): string (uri)
  HTTPS callback endpoint. HTTP endpoints are rejected by default.
• confirmations: integer
  Minimum Value: 0

  Required block confirmations before callbacks are emitted.
• endBlock: integer (int64)
  Minimum Value: 0

  Highest block number to process before the subscription is considered complete.
• expiresAt: string (date-time)
  Optional RFC 3339 timestamp after which the subscription is automatically expired.
• logsFilter: object EventSubscriptionLogsFilter
  Log filter criteria for a logs event subscription. Topic positions are ordered. Nested topic arrays (OR topic sets) are not supported.The filter is validated with eth_getLogs when the subscription is created.
• maxCallbackRetry: integer
  Minimum Value: 1

  Maximum number of delivery attempts before a payload is dead-lettered.
• nonEmptyBlocksOnly: boolean
  When true, newHeads callbacks are emitted only for blocks that contain at least one transaction; empty blocks are not delivered.
• oauth: object EventSubscriptionOAuthConfig
  OAuth 2.0 configuration for callback authentication.
• retryBaseMs: integer
  Minimum Value: 1

  Initial delay in milliseconds used when scheduling callback retries.
• retryMaxMs: integer
  Minimum Value: 1

  Upper bound in milliseconds for retry backoff; must be greater than or equal to retryBaseMs.
• startBlock: integer (int64)
  Minimum Value: 0

  Earliest block number to begin processing; omit to start from the current chain state.
• tls: object EventSubscriptionTlsConfig
  TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
• type(required): string
  Allowed Values: [ "newHeads", "logs" ]

  Event type to subscribe to; supported values are newHeads and logs.

{
    "type":"object",
    "description":"Request to create a Besu event subscription. Supports recoverable event types only: `newHeads` and `logs`. `logsFilter` is only valid when `type=logs`.\n`nonEmptyBlocksOnly` is only valid when `type=newHeads`.",
    "required":[
        "type",
        "callbackUrl"
    ],
    "properties":{
        "type":{
            "type":"string",
            "enum":[
                "newHeads",
                "logs"
            ],
            "description":"Event type to subscribe to; supported values are <code>newHeads</code> and <code>logs</code>."
        },
        "callbackUrl":{
            "type":"string",
            "format":"uri",
            "description":"HTTPS callback endpoint. HTTP endpoints are rejected by default."
        },
        "confirmations":{
            "type":"integer",
            "minimum":0,
            "description":"Required block confirmations before callbacks are emitted."
        },
        "nonEmptyBlocksOnly":{
            "type":"boolean",
            "description":"When <code>true</code>, <code>newHeads</code> callbacks are emitted only for blocks that contain at least one transaction; empty blocks are not delivered."
        },
        "startBlock":{
            "type":"integer",
            "format":"int64",
            "minimum":0,
            "description":"Earliest block number to begin processing; omit to start from the current chain state."
        },
        "endBlock":{
            "type":"integer",
            "format":"int64",
            "minimum":0,
            "description":"Highest block number to process before the subscription is considered complete."
        },
        "expiresAt":{
            "type":"string",
            "format":"date-time",
            "description":"Optional RFC 3339 timestamp after which the subscription is automatically expired."
        },
        "maxCallbackRetry":{
            "type":"integer",
            "minimum":1,
            "description":"Maximum number of delivery attempts before a payload is dead-lettered."
        },
        "retryBaseMs":{
            "type":"integer",
            "minimum":1,
            "description":"Initial delay in milliseconds used when scheduling callback retries."
        },
        "retryMaxMs":{
            "type":"integer",
            "minimum":1,
            "description":"Upper bound in milliseconds for retry backoff; must be greater than or equal to <code>retryBaseMs</code>."
        },
        "oauth":{
            "$ref":"#/components/schemas/EventSubscriptionOAuthConfig",
            "description":"OAuth callback authentication configuration for token acquisition and credential transport."
        },
        "tls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"TLS or mTLS configuration for callback transport."
        },
        "logsFilter":{
            "$ref":"#/components/schemas/EventSubscriptionLogsFilter",
            "description":"Log filter criteria applied when <code>type</code> is <code>logs</code>."
        }
    }
}

Nested Schema : EventSubscriptionLogsFilter

Type: object

Log filter criteria for a logs event subscription. Topic positions are ordered. Nested topic arrays (OR topic sets) are not supported.The filter is validated with eth_getLogs when the subscription is created.

Show Source

• address: string
  Minimum Length: 42

  Maximum Length: 42

  Pattern: ^0x[0-9a-fA-F]{40}$

  Contract address whose logs are included.
• topics: array topics
  Maximum Number of Items: 4

  Ordered topic filters; use null entries as wildcards for positional topics.

{
    "type":"object",
    "description":"Log filter criteria for a <code>logs</code> event subscription. Topic positions are ordered. Nested topic arrays (OR topic sets) are not supported.The filter is validated with <code>eth_getLogs</code> when the subscription is created.",
    "properties":{
        "address":{
            "type":"string",
            "description":"Contract address whose logs are included.",
            "pattern":"^0x[0-9a-fA-F]{40}$",
            "minLength":42,
            "maxLength":42
        },
        "topics":{
            "type":"array",
            "maxItems":4,
            "items":{
                "type":[
                    "string",
                    "null"
                ],
                "pattern":"^0x[0-9a-fA-F]{64}$",
                "minLength":66,
                "maxLength":66
            },
            "description":"Ordered topic filters; use null entries as wildcards for positional topics."
        }
    }
}

Nested Schema : EventSubscriptionOAuthConfig

Type: object

OAuth 2.0 configuration for callback authentication.

Show Source

• authInHeader: boolean
  Default Value: true

  Controls OAuth token request client-auth placement. When true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint. When false, sends client_id and client_secret form fields in the token request body.
• clientId(required): string
  OAuth 2.0 client identifier registered for the callback endpoint.
• clientSecret(required): string
  OAuth 2.0 client secret used for token acquisition.
• grantType: string
  Default Value: client_credentials

  Allowed Values: [ "client_credentials", "refresh_token" ]

  OAuth 2.0 token grant used for callback access-token acquisition. client_credentials obtains an access token with the configured client credentials. refresh_token uses the supplied refreshToken and retains any replacement refresh token returned by the identity provider.
• refreshToken: string
  Required when grantType=refresh_token; pre-provisioned OAuth refresh token used to mint callback access tokens.
• scopes: string
  Space-delimited OAuth scopes requested during token exchange.
• tls: object EventSubscriptionTlsConfig
  TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
• tokenTls: object EventSubscriptionTlsConfig
  TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.
• tokenUrl(required): string (uri)
  OAuth 2.0 token endpoint used to obtain access tokens for callbacks.

{
    "type":"object",
    "description":"OAuth 2.0 configuration for callback authentication.",
    "required":[
        "tokenUrl",
        "clientId",
        "clientSecret"
    ],
    "allOf":[
        {
            "if":{
                "required":[
                    "grantType"
                ],
                "properties":{
                    "grantType":{
                        "const":"refresh_token"
                    }
                }
            },
            "then":{
                "required":[
                    "refreshToken"
                ]
            }
        }
    ],
    "properties":{
        "tokenUrl":{
            "type":"string",
            "format":"uri",
            "description":"OAuth 2.0 token endpoint used to obtain access tokens for callbacks."
        },
        "clientId":{
            "type":"string",
            "description":"OAuth 2.0 client identifier registered for the callback endpoint."
        },
        "clientSecret":{
            "type":"string",
            "description":"OAuth 2.0 client secret used for token acquisition."
        },
        "grantType":{
            "type":"string",
            "enum":[
                "client_credentials",
                "refresh_token"
            ],
            "default":"client_credentials",
            "description":"OAuth 2.0 token grant used for callback access-token acquisition.\n<code>client_credentials</code> obtains an access token with the configured client credentials.\n<code>refresh_token</code> uses the supplied <code>refreshToken</code> and retains any replacement refresh token returned by the identity provider.\n"
        },
        "refreshToken":{
            "type":"string",
            "description":"Required when <code>grantType=refresh_token</code>; pre-provisioned OAuth refresh token used to mint callback access tokens."
        },
        "scopes":{
            "type":"string",
            "description":"Space-delimited OAuth scopes requested during token exchange."
        },
        "authInHeader":{
            "type":"boolean",
            "default":true,
            "description":"Controls OAuth token request client-auth placement.\nWhen true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint.\nWhen false, sends <code>client_id</code> and <code>client_secret</code> form fields in the token request body.\n"
        },
        "tokenTls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"Optional TLS or mTLS transport configuration used only for OAuth token-endpoint requests."
        },
        "tls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"OAuth token endpoint TLS configuration. Use <code>tokenTls</code> for new integrations."
        }
    }
}

Match All

OAuth 2.0 configuration for callback authentication.

Show Source

{
    "type":"object",
    "description":"OAuth 2.0 configuration for callback authentication.",
    "required":[
        "tokenUrl",
        "clientId",
        "clientSecret"
    ],
    "allOf":[
        {
            "if":{
                "required":[
                    "grantType"
                ],
                "properties":{
                    "grantType":{
                        "const":"refresh_token"
                    }
                }
            },
            "then":{
                "required":[
                    "refreshToken"
                ]
            }
        }
    ],
    "properties":{
        "tokenUrl":{
            "type":"string",
            "format":"uri",
            "description":"OAuth 2.0 token endpoint used to obtain access tokens for callbacks."
        },
        "clientId":{
            "type":"string",
            "description":"OAuth 2.0 client identifier registered for the callback endpoint."
        },
        "clientSecret":{
            "type":"string",
            "description":"OAuth 2.0 client secret used for token acquisition."
        },
        "grantType":{
            "type":"string",
            "enum":[
                "client_credentials",
                "refresh_token"
            ],
            "default":"client_credentials",
            "description":"OAuth 2.0 token grant used for callback access-token acquisition.\n<code>client_credentials</code> obtains an access token with the configured client credentials.\n<code>refresh_token</code> uses the supplied <code>refreshToken</code> and retains any replacement refresh token returned by the identity provider.\n"
        },
        "refreshToken":{
            "type":"string",
            "description":"Required when <code>grantType=refresh_token</code>; pre-provisioned OAuth refresh token used to mint callback access tokens."
        },
        "scopes":{
            "type":"string",
            "description":"Space-delimited OAuth scopes requested during token exchange."
        },
        "authInHeader":{
            "type":"boolean",
            "default":true,
            "description":"Controls OAuth token request client-auth placement.\nWhen true, sends `clientId:clientSecret` in an HTTP Basic Authorization header to the token endpoint.\nWhen false, sends <code>client_id</code> and <code>client_secret</code> form fields in the token request body.\n"
        },
        "tokenTls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"Optional TLS or mTLS transport configuration used only for OAuth token-endpoint requests."
        },
        "tls":{
            "$ref":"#/components/schemas/EventSubscriptionTlsConfig",
            "description":"OAuth token endpoint TLS configuration. Use <code>tokenTls</code> for new integrations."
        }
    }
}

Nested Schema : EventSubscriptionTlsConfig

Type: object

TLS or mTLS configuration for callback delivery. If mTLS is used, both clientCert and clientKey must be provided together.

Show Source

• caCert: string
  PEM-encoded CA certificate used to verify callback server certificates.
• clientCert: string
  PEM-encoded client certificate for callback mTLS.
• clientKey: string
  PEM-encoded PKCS#8 private key for callback mTLS.
• insecureSkipVerify: boolean
  Default Value: false

  When true, skips TLS certificate verification. Use only in controlled non-production environments.

{
    "type":"object",
    "description":"TLS or mTLS configuration for callback delivery. If mTLS is used, both <code>clientCert</code> and <code>clientKey</code> must be provided together.",
    "properties":{
        "caCert":{
            "type":"string",
            "description":"PEM-encoded CA certificate used to verify callback server certificates."
        },
        "clientCert":{
            "type":"string",
            "description":"PEM-encoded client certificate for callback mTLS."
        },
        "clientKey":{
            "type":"string",
            "description":"PEM-encoded PKCS#8 private key for callback mTLS."
        },
        "insecureSkipVerify":{
            "type":"boolean",
            "default":false,
            "description":"When <code>true</code>, skips TLS certificate verification. Use only in controlled non-production environments."
        }
    }
}

Nested Schema : topics

Type: array

Maximum Number of Items: 4

Ordered topic filters; use null entries as wildcards for positional topics.

Show Source

• Array of: [ "string", "null" ]
  Minimum Length: 66

  Maximum Length: 66

  Pattern: ^0x[0-9a-fA-F]{64}$

{
    "type":"array",
    "maxItems":4,
    "items":{
        "type":[
            "string",
            "null"
        ],
        "pattern":"^0x[0-9a-fA-F]{64}$",
        "minLength":66,
        "maxLength":66
    },
    "description":"Ordered topic filters; use null entries as wildcards for positional topics."
}

Examples

Select an example Minimal newHeads subscription newHeads subscription with finite range and expiry newHeads subscription that only emits blocks with transactions Logs subscription with OAuth callback authorization Logs subscription with refresh-token OAuth callback authorization Logs subscription with default retry settings and no secrets

Back to Top

Response

Supported Media Types

• application/json

201 Response

Returns the created event subscription.

Body ()

Root Schema : EventSubscriptionResponse

Type: object

Event subscription configuration and current lifecycle state.

Show Source

• callbackUrl: string
  HTTPS endpoint receiving callback deliveries.
• confirmations: integer
  Block confirmation threshold configured for the subscription.
• cursor: object EventSubscriptionCursor
  Event processing position for an event subscription.
• endBlock: integer (int64)
  Final block number to process before stopping, when provided.
• expiresAt: string (date-time)
  Timestamp after which the subscription is automatically considered expired.
• nonEmptyBlocksOnly: boolean
  Indicates whether empty newHeads blocks are suppressed for this subscription.
• startBlock: integer (int64)
  First block number considered when replaying events, when provided.
• stateChangedAt: string (date-time)
  Timestamp when the lifecycle status was most recently updated.
• stateReason: string
  Optional transition reason for terminal state changes.
• status: string
  Current lifecycle state of the subscription (running, stopped, deleted, completed, or expired).
• subId: string
  Unique identifier for the subscription.
• type: string
  Event type for the subscription (newHeads or logs).

{
    "type":"object",
    "description":"Event subscription configuration and current lifecycle state.",
    "properties":{
        "subId":{
            "type":"string",
            "description":"Unique identifier for the subscription."
        },
        "type":{
            "type":"string",
            "description":"Event type for the subscription (<code>newHeads</code> or <code>logs</code>)."
        },
        "status":{
            "type":"string",
            "description":"Current lifecycle state of the subscription (<code>running</code>, <code>stopped</code>, <code>deleted</code>, <code>completed</code>, or <code>expired</code>)."
        },
        "stateReason":{
            "type":"string",
            "description":"Optional transition reason for terminal state changes."
        },
        "stateChangedAt":{
            "type":"string",
            "format":"date-time",
            "description":"Timestamp when the lifecycle status was most recently updated."
        },
        "callbackUrl":{
            "type":"string",
            "description":"HTTPS endpoint receiving callback deliveries."
        },
        "confirmations":{
            "type":"integer",
            "description":"Block confirmation threshold configured for the subscription."
        },
        "nonEmptyBlocksOnly":{
            "type":"boolean",
            "description":"Indicates whether empty <code>newHeads</code> blocks are suppressed for this subscription."
        },
        "startBlock":{
            "type":"integer",
            "format":"int64",
            "description":"First block number considered when replaying events, when provided."
        },
        "endBlock":{
            "type":"integer",
            "format":"int64",
            "description":"Final block number to process before stopping, when provided."
        },
        "expiresAt":{
            "type":"string",
            "format":"date-time",
            "description":"Timestamp after which the subscription is automatically considered expired."
        },
        "cursor":{
            "$ref":"#/components/schemas/EventSubscriptionCursor"
        }
    }
}

Nested Schema : EventSubscriptionCursor

Type: object

Event processing position for an event subscription.

Show Source

• lastFinalizedBlock: integer (int64)
  Most recent finalized block used for head progression.
• lastFinalizedBlockHash: string
  Block hash for lastFinalizedBlock, when known.
• lastLogBlock: integer (int64)
  Most recent block used for log delivery.
• lastLogBlockHash: string
  Block hash for lastLogBlock, when known.
• lastLogIndex: integer
  Last delivered log index in lastLogBlock when resuming within-block.
• lastLogTxIndex: integer
  Last delivered transaction index in lastLogBlock when resuming within-block.

{
    "type":"object",
    "description":"Event processing position for an event subscription.",
    "properties":{
        "lastFinalizedBlock":{
            "type":"integer",
            "format":"int64",
            "description":"Most recent finalized block used for head progression."
        },
        "lastFinalizedBlockHash":{
            "type":"string",
            "description":"Block hash for <code>lastFinalizedBlock</code>, when known."
        },
        "lastLogBlock":{
            "type":"integer",
            "format":"int64",
            "description":"Most recent block used for log delivery."
        },
        "lastLogBlockHash":{
            "type":"string",
            "description":"Block hash for <code>lastLogBlock</code>, when known."
        },
        "lastLogTxIndex":{
            "type":"integer",
            "description":"Last delivered transaction index in <code>lastLogBlock</code> when resuming within-block."
        },
        "lastLogIndex":{
            "type":"integer",
            "description":"Last delivered log index in <code>lastLogBlock<code> when resuming within-block."
        }
    }
}

Examples

Select an example response_201_subscription_created newHeads subscription with end block and expiry

400 Response

Validation failed.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_400_validation_error HTTPS enforcement failure

500 Response

Unexpected service error.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_500_internal_error

503 Response

Event subscriptions are unavailable.

Body ()

Root Schema : ErrorResponse

Type: object

Error response returned by the service.

Show Source

• decodedError:
  Returned only when `decode.errors=true` and decodable revert bytes are present.
• error: string
  Short error summary suitable for display.
• hint: [ "string", "null" ]
  Optional guidance for resolving the error.
• message: [ "string", "null" ]
  Additional error details, when available.
• policy:
  Present for policy warnings or denials such as preflight failure.
• preflight:
  Present for preflight-gated transaction submission errors.
• requestId: [ "string", "null" ]
  Client-provided correlation ID echoed in the response.
• upstreamCode: [ "integer", "null" ]
  Besu node error code, when provided by the RPC endpoint.
• upstreamData: [ "string", "null" ]
  Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available.
• upstreamError: [ "object", "null" ] upstreamError
  Additional Properties Allowed: true

  Complete error object returned by the Besu node, including code, message, and data fields, when available.

{
    "type":"object",
    "description":"Error response returned by the service.",
    "properties":{
        "error":{
            "type":"string",
            "description":"Short error summary suitable for display."
        },
        "message":{
            "type":[
                "string",
                "null"
            ],
            "description":"Additional error details, when available."
        },
        "hint":{
            "type":[
                "string",
                "null"
            ],
            "description":"Optional guidance for resolving the error."
        },
        "upstreamCode":{
            "type":[
                "integer",
                "null"
            ],
            "description":"Besu node error code, when provided by the RPC endpoint."
        },
        "upstreamData":{
            "type":[
                "string",
                "null"
            ],
            "description":"Error data returned by the Besu node in 0x-prefixed hexadecimal or JSON format, when available."
        },
        "upstreamError":{
            "type":[
                "object",
                "null"
            ],
            "additionalProperties":true,
            "description":"Complete error object returned by the Besu node, including code, message, and data fields, when available."
        },
        "decodedError":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/DecodedError"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Returned only when `decode.errors=true` and decodable revert bytes are present."
        },
        "preflight":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPreflightResult"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for preflight-gated transaction submission errors."
        },
        "policy":{
            "anyOf":[
                {
                    "$ref":"#/components/schemas/TransactionPolicyDecision"
                },
                {
                    "type":"null"
                }
            ],
            "description":"Present for policy warnings or denials such as preflight failure."
        },
        "requestId":{
            "type":[
                "string",
                "null"
            ],
            "description":"Client-provided correlation ID echoed in the response."
        }
    }
}

Nested Schema : upstreamError

Type: object

Additional Properties Allowed: true

Complete error object returned by the Besu node, including code, message, and data fields, when available.

Examples

Select an example response_503_feature_disabled

Back to Top