Errors

Failed JSON requests return a stable code and message:

{
  "error": {
    "code": "insufficient_scope",
    "message": "This broker access token cannot access connection ..."
  }
}

Authorization required

An OAuth-backed connection that is not ready returns 401:

{
  "error": {
    "code": "authorization_required",
    "message": "Connection requires authorization.",
    "authorize_url": "https://provider.example/authorize?...",
    "expires_at": "2026-08-12T18:00:00.000Z"
  }
}

@hookfish/sdk exposes these as HookfishError.authorizeUrl and HookfishError.expiresAt. The SDK also preserves the HTTP status as status and the parsed response as body. HookfishError.getResponse() reconstructs the failed HTTP response, so Hono propagates an unhandled error without losing its status or JSON body. Applications can still translate those fields in an onError handler when they need a different public contract.

Provider scope not granted

If an authorization server grants fewer provider scopes than you requested, later access that requires a missing scope returns 403 scope_not_granted:

{
  "error": {
    "code": "scope_not_granted",
    "message": "Connection was authorized without all required scopes.",
    "requested_scopes": ["read", "write", "admin"],
    "granted_scopes": ["read", "write"],
    "missing_scopes": ["admin"]
  }
}

This error is terminal for the current grant. Ask the user to change provider permissions before explicitly starting another flow with connections.authorize(). Hookfish does not start another consent flow from access() for scopes the provider already declined.

Common codes

Status	Code	Meaning
`400`	`invalid_connection_path`	Path is empty or is not a canonical resource identifier
`400`	`invalid_provider_id`	Final segment is not an allowed provider ID
`400`	`invalid_connection_configuration`	MCP URL is missing or invalid
`401`	`authorization_required`	Open the fresh URL to make the connection ready
`401`	`unauthorized`	Broker credential is missing or incorrect
`403`	`insufficient_scope`	Broker credential does not cover the exact path or subtree
`403`	`scope_not_granted`	Provider omitted one or more scopes requested for the current grant
`404`	`unknown_provider`	Final path segment has no trusted implementation
`404`	`secret_required`	Static connection has no stored value
`409`	`authorization_superseded`	A newer access replaced this pending flow
`409`	`connection_configuration_conflict`	Existing connection has different immutable configuration
`409`	`secret_assignment_unsupported`	Provider does not accept caller-supplied secrets
`500`	`missing_configuration`	Required deployment setting is absent
`502`	`token_exchange_failed`	Upstream exchange or refresh failed

Branch on code, not message text. Do not forward provider diagnostics or successful access payloads to browser code.

Configuration

HTTP API

Security

License

Authorization required

Provider scope not granted

Common codes

​Authorization required

​Provider scope not granted

​Common codes

Authorization required

Provider scope not granted

Common codes