Error Handling

WispHive returns concise production errors designed for client-side branching and operational debugging.

Error envelope

{
  "error": "registration not found",
  "status": 400
}

Some routes also include X-Request-ID response headers for operational trace correlation.

Status	Meaning	Typical cause
`201`	Created	Integration was provisioned successfully
`200`	Accepted	Callback or redirect orchestration succeeded
`302`	Redirect	Browser is being redirected to the provider or the signed return URL
`308`	Permanent redirect	Legacy docs aliases redirected to `/`
`401`	Unauthorized	Missing or invalid API key header
`400`	Validation error	Missing field, unsupported registration type, invalid URL, UUID, or token
`404`	Not found	Unknown route or unavailable documentation build
`413`	Payload too large	Request exceeded configured size limit
`503`	Dependency unavailable	Event publishing infrastructure or runtime dependency unavailable

Message	Meaning
`registration not found`	The submitted `registration_id` does not exist
`registration type is not supported for oauth integrations`	Only SME, education, and ISP registrations are supported
`oauth_client_secret is required`	Hosted OAuth integrations currently require confidential client credentials
`captive_portal_url is required`	No portal URL was provided and none could be derived from the registration
`idempotency key is required`	AAA callbacks must provide `Idempotency-Key`
`api key is required`	Missing `X-API-Key` on protected API endpoints
`api key is invalid`	Provided API key did not match an active key
`integration callback is invalid`	The callback URL path or token does not map to an active integration
`wisphive_token is required`	Missing callback signing credential
`userid is required`	Missing stable user UUID
`derived_username is required`	Missing derived username alias
`derived_email is required`	Missing derived email alias
`derived_email must use the assigned derived email domain`	The callback used an email outside the entity's assigned `*.id.wisphive.net` domain
`user_session_id is required`	Missing user session identifier
`derived_username must use the assigned derived name prefix`	The callback used a username outside the entity's assigned namespace
`sensitive user fields are not accepted in aaa handoff; use derived_username, derived_email, and user_session_id`	The callback included direct user data such as email or display name