/**
 * REST error envelope + HTTP status mapping. Every non-200 response carries the
 * full envelope in the body. Status is keyed on exact codes/stages — NEVER a
 * substring scan of free text (a reason sentence containing "timeout" must not
 * map to 504; 504 only comes from the route-deadline path).
 */
export interface ErrorEnvelope {
    ok: false;
    error: string;
    error_reason: string;
    stage?: string;
    hint?: string;
}
export interface HttpError {
    status: number;
    body: ErrorEnvelope;
    headers: Record<string, string>;
}
export declare function errorEnvelope(error_reason: string, error: string, extra?: {
    stage?: string;
    hint?: string;
}): ErrorEnvelope;
export declare function invalidJson(): HttpError;
export declare function invalidInput(detail: string): HttpError;
export declare function unauthorized(hint: string): HttpError;
export declare function forbidden(reason: string, hint: string): HttpError;
export declare function notFound(): HttpError;
export declare function methodNotAllowed(allow: string): HttpError;
export declare function bodyTooLarge(capBytes: number): HttpError;
export declare function tooManyRequests(): HttpError;
export declare function internalError(): HttpError;
export declare function notImplemented(tool: string): HttpError;
export declare function routeTimeout(tool: string): HttpError;
export interface StageFailure {
    error: string;
    error_reason: string;
    stage: string;
}
/**
 * Map a StageResult failure to an HTTP status. Conservative + table-driven:
 * 503 for known unavailability, 502 for fetch-stage upstream failures, 400 for
 * the explicit semantic-validation allowlist, else 500. Never substring-scans.
 */
export declare function statusForStageResult(f: StageFailure): number;
/**
 * Map a crawl/cache in-band error to an HTTP status. The value passed is either
 * a stable ssrf code (→ 400) or an upstream fetch reason code (→ 502); anything
 * else (free-text messages) → 500. No substring matching.
 */
export declare function statusForCrawlCacheError(errorKey: string): number;
/**
 * Search returns `ok:true` with an optional `data.error`. A set `error`
 * (all-engines-failed) is mapped like a failure (500). A `warning`-only /
 * degraded result stays 200 → return null (no remap).
 */
export declare function statusForSearchData(data: {
    error?: unknown;
    warning?: unknown;
}): number | null;
//# sourceMappingURL=errors.d.ts.map