hasura/graphql-engine · error · Error

Unexpected status code: {0}

Error message

Unexpected status code: {0}

What it means

The pre-route hook returned an HTTP status the executor does not accept (anything other than the defined success/continue statuses). The numeric code is embedded in the message.

Source

Thrown at v3/crates/plugins/pre-route-plugin/src/execute.rs:28

use open_dds::plugins::{
    LifecyclePreRoutePluginHook, LifecyclePreRoutePluginHookConfigRequestMethod,
    LifecyclePreRoutePluginHookIncomingHTTPMethod,
};
use serde_json::json;
use tracing_util::{
    ErrorVisibility, SpanVisibility, Traceable, TraceableError, set_attribute_on_active_span,
};

#[derive(Debug, thiserror::Error)]
pub enum Error {
    #[error("Error while making the HTTP request to the pre-parse plugin {0} - {1}")]
    ErrorWhileMakingHTTPRequestToTheHook(String, reqwest::Error),
    #[error("Error while building the request for the pre-parse plugin {0} - {1}")]
    BuildRequestError(String, String),
    #[error("Reqwest error: {0}")]
    ReqwestError(reqwest::Error),
    #[error("Unexpected status code: {0}")]
    UnexpectedStatusCode(u16),
    #[error("Error parsing the request: {0}")]
    PluginRequestParseError(serde_json::error::Error),
    #[error("HTTP method {0} not supported")]
    UnsupportedHTTPMethod(String),
    #[error("Invalid header name {0}")]
    InvalidHeaderName(String),
    #[error("Invalid header value {0}")]
    InvalidHeaderValue(String),
    #[error("Not found")]
    NotFound,
    // Only used in the pre-route plugin handler function. Defined to ensure consistent
    // response formatting in IntoResponse impl.
    #[error("Cannot load pre-route plugins: {0}")]
    CannotLoadPlugins(String),
}

impl TraceableError for Error {

View on GitHub (pinned to 724551b9ae)

Solutions

1. Check hook logs to find why it rejected the call.
2. Verify the hook route and payload contract match the engine's pre-route plugin version.
3. Fix auth token configuration on both sides.
4. Redeploy matching engine/plugin versions.

if let Error::UnexpectedStatusCode(code) = &err {
    match code { 401 | 403 => fix_auth(), 404 => fix_hook_path(), _ => inspect_hook_logs() }
}

When it happens

Trigger: Hook returns 404 (endpoint moved), 401/403 (auth mismatch), or 500 (hook bug) when the engine calls it before routing.

Common situations: Plugin and engine version drift changing the hook path; missing/rotated auth token on the hook; hook failing on specific request shapes.

Related errors

• Unexpected status code: {0}
• Unexpected status code: {0}
• Unexpected status code: {0}
• Error while making the HTTP request to the pre-parse plugin
• Error while building the request for the pre-parse plugin {0

AI-assisted analysis of hasura/graphql-engine@724551b9ae (2026-08-28). Data as JSON: /api/errors/aaed5a657e2e24c1. Report an issue: GitHub.