Step-Up Hook Failed

The step_up.hook_failed event is triggered when Prelude calls your step-up delegation hook and the call cannot be completed successfully. Use this event to monitor the health of your delegation endpoint and alert on outages or misconfiguration.

Failure reasons

The reason field identifies the precise rule that failed. It is one of the following values:

Transport-level

Reason	Description
`request_failed`	The HTTP request to your delegation hook could not be completed (DNS failure, connection refused, TLS error, timeout exceeding 5 seconds, etc.).
`invalid_status_code`	The hook returned a non-2xx HTTP status code.

Response-level

The following reasons are emitted when the hook returns 200 but the body does not match the expected response schema:

Reason	Description
`response_decode_failed`	The response body could not be parsed as JSON (malformed JSON, wrong content type, body exceeding the 64 KB limit, etc.).
`invalid_status`	The `status` field was missing or not one of `continue`, `review`, or `block`.
`missing_steps`	The response had `status: "review"` but no `steps` were provided.
`invalid_granted_for`	`granted_for` was negative, exceeded the 24-hour maximum (86,400 seconds), or was zero for a `grant_mode` that requires a positive duration.
`invalid_grant_mode`	`grant_mode` was missing or not one of `single-use`, `session-bound`, or `profile-bound`.
`invalid_step`	One of the `steps` had an invalid `key` (must match `[a-zA-Z0-9._:-]+`) or an `expiration_duration` that was negative or exceeded the 24-hour maximum.
`invalid_response`	Fallback emitted when the response is invalid but does not match any of the more specific reasons above.

Event payload

Emitted when Prelude calls your step-up delegation hook and the call cannot be completed successfully.

user_id

string

required

An app's user's unique identifier. It is prefixed with 'usr_'

Examples:

"usr_01jqebhswje1ka1z7ahr9rfsgt"

"usr_01jqy7455pf8p9bap5qke912g1"

session_id

string

required

A user's session unique identifier. It is prefixed with 'ses_'

Example:

"ses_01jr0z5w2seq998trz7ftbb9rj"

scope

string

required

The step-up scope that was being requested.

Example:

"transfer_funds"

reason

enum<string>

required

The reason the delegation hook call failed. Transport-level reasons describe failures reaching the hook; response-level reasons describe failures validating the response body.

Available options:

invalid_granted_for,

invalid_grant_mode,

invalid_status,

invalid_status_code,

invalid_step,

invalid_response,

missing_steps,

request_failed,

response_decode_failed

Example:

"invalid_grant_mode"

occurred_at

string<date-time>

required

Example:

"2025-03-15T10:30:00Z"

dispatch_id

string

Example:

"123e4567-e89b-12d3-a456-426614174000"

correlation_id

string

Example:

"123e4567-e89b-12d3-a456-426614174000"

Documentation

API Reference

Failure reasons

Transport-level

Response-level

Event payload

​Failure reasons

​Transport-level

​Response-level

​Event payload

Failure reasons

Transport-level

Response-level

Event payload