Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.prelude.so/llms.txt

Use this file to discover all available pages before exploring further.

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

ReasonDescription
request_failedThe HTTP request to your delegation hook could not be completed (DNS failure, connection refused, TLS error, timeout exceeding 5 seconds, etc.).
invalid_status_codeThe 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:
ReasonDescription
response_decode_failedThe response body could not be parsed as JSON (malformed JSON, wrong content type, body exceeding the 64 KB limit, etc.).
invalid_statusThe status field was missing or not one of continue, review, or block.
missing_stepsThe response had status: "review" but no steps were provided.
invalid_granted_forgranted_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_modegrant_mode was missing or not one of single-use, session-bound, or profile-bound.
invalid_stepOne 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_responseFallback 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"