Reference

Error Reference

All HyperSearchX API errors follow a consistent JSON format with machine-readable error codes, human-readable messages, and a unique request ID for support.

Error format

json

{
  "error": {
    "code": "invalid_request",
    "message": "Human-readable description of what went wrong.",
    "field": "query",
    "request_id": "req_01j8xk3m7p4qr5st6uv7wx8yz"
  }
}

Field	Type	Description
`code`	string	Machine-readable error identifier
`message`	string	Human-readable explanation
`field`	string?	Request field that caused the error (validation errors)
`request_id`	string	Unique ID — include when contacting support

HTTP status codes

Status	Meaning
`200`	Success
`400`	Bad request — validation error in request body
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — key lacks required scope
`404`	Not found — endpoint does not exist
`422`	Unprocessable — request parsed but semantically invalid
`429`	Rate limited — per-minute or monthly quota exceeded
`500`	Internal server error
`503`	Service unavailable — upstream dependency down

Error codes

Authentication errors (401)

Code	Cause
`missing_auth`	No Authorization header provided
`invalid_auth`	Authorization header is not a Bearer token
`invalid_key`	API key not found or has been revoked
`expired_key`	API key has passed its expiration date

Authorization errors (403)

Code	Cause
`insufficient_scope`	Key does not have permission for this endpoint

Validation errors (400)

Code	Cause
`invalid_request`	Request body validation failed (see `field`)
`query_too_long`	Query exceeds 500 characters
`invalid_tier`	Unknown tier value (must be key_facts, summary, detailed, complete)
`invalid_budget`	token_budget out of range (100–10,000 for search)
`invalid_sources`	max_sources out of range (1–20)
`invalid_url`	Provided URL is not valid or not accessible
`payload_too_large`	Request body exceeds 1 MB limit

Rate limit errors (429)

Code	Cause
`rate_limited`	Per-minute limit exceeded; wait `Retry-After` seconds
`quota_exceeded`	Monthly quota exhausted; upgrade plan or wait for reset

Server errors (500 / 503)

Code	Cause
`internal_error`	Unexpected server error; please retry
`upstream_error`	A search backend returned an error; results may be partial
`timeout`	Request exceeded the 60-second processing limit
`service_unavailable`	Critical dependency is down; check status page

Example error handling

error-handling.ts

interface HsxError {
  code: string;
  message: string;
  field?: string;
  request_id: string;
}

async function search(query: string) {
  const res = await fetch("https://api.hypersearchx.zuhabul.com/v1/search", {
    method: "POST",
    headers: {
      "Authorization": `Bearer ${process.env.HSX_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, tier: "summary" }),
  });

  if (!res.ok) {
    const body = await res.json();
    const err: HsxError = body.error;

    switch (err.code) {
      case "rate_limited": {
        const retryAfter = parseInt(res.headers.get("Retry-After") ?? "60", 10);
        throw new Error(`Rate limited. Retry after ${retryAfter}s`);
      }
      case "quota_exceeded":
        throw new Error("Monthly quota exhausted. Please upgrade your plan.");
      case "invalid_key":
        throw new Error("Invalid API key. Check HSX_API_KEY.");
      default:
        throw new Error(`API error [${err.code}]: ${err.message} (req: ${err.request_id})`);
    }
  }

  return res.json();
}