/** Context captured on every typed error. */
export interface CyborgDBErrorContext {
    /** HTTP status, or null for transport failures and pre-flight validation. */
    statusCode?: number | null;
    /** Service correlation id, or null when the service did not supply one. */
    requestId?: string | null;
    /** The service's own message, or null when there was no response. */
    detail?: string | null;
    /** Retry-After in seconds, or null when absent. */
    retryAfter?: number | null;
    /** Index this call targeted, when the call site knows it. */
    indexName?: string | null;
    /** The originating error. */
    cause?: unknown;
}
/**
 * Base class for every error this SDK throws. Catch it to handle any CyborgDB
 * failure; catch a subclass to handle one kind.
 */
export declare class CyborgDBError extends Error {
    readonly statusCode: number | null;
    readonly requestId: string | null;
    readonly detail: string | null;
    readonly retryAfter: number | null;
    readonly indexName: string | null;
    /**
     * Whether backing off and retrying can succeed. Fixed per error type —
     * retry loops branch on this rather than re-deriving a status table.
     */
    readonly retryable: boolean;
    constructor(message: string, context?: CyborgDBErrorContext);
}
/**
 * HTTP 400 and 422, and arguments this SDK rejects before sending the request
 * (including an unusable `baseUrl`). `statusCode` is null when caught
 * pre-flight.
 */
export declare class CyborgDBValidationError extends CyborgDBError {
    readonly retryable = false;
}
/** HTTP 401 and 403. Check the API key and its permissions. */
export declare class CyborgDBAuthenticationError extends CyborgDBError {
    readonly retryable = false;
}
/** HTTP 404 — the collection or item does not exist. */
export declare class CyborgDBNotFoundError extends CyborgDBError {
    readonly retryable = false;
}
/**
 * HTTP 409 — a state conflict, such as training while training is already in
 * progress. Poll for the terminal state; a backoff loop must not retry a 409.
 */
export declare class CyborgDBConflictError extends CyborgDBError {
    readonly retryable = false;
}
/**
 * HTTP 429. Honor `retryAfter` when set.
 *
 * The service does not rate-limit yet (cyborgdb-core#2386); this type exists so
 * callers can write the handler once.
 */
export declare class CyborgDBRateLimitError extends CyborgDBError {
    readonly retryable = true;
}
/** Any 5xx. Not "ServiceUnavailable": a 500 is a server bug, not unavailability. */
export declare class CyborgDBServiceError extends CyborgDBError {
    readonly retryable = true;
}
/**
 * No HTTP response reached the client — DNS failure, connection refused, TLS
 * failure, or timeout. `statusCode` is null.
 *
 * Timeouts land here too: a timeout and a refused connection have the same
 * caller action, and the difference is diagnostic — read `detail`.
 */
export declare class CyborgDBTransportError extends CyborgDBError {
    readonly retryable = true;
}
/**
 * Normalize an error from the generated API client and throw the typed error
 * the taxonomy names for its status. Never returns.
 *
 * Statuses the taxonomy does not name (405, 413, ...) throw the base
 * `CyborgDBError`. Only a failure with no status that is not a network
 * failure stays a plain `Error`.
 */
export declare function handleApiError(error: unknown, context?: {
    indexName?: string;
}): never;
/**
 * Safely extract a `detail` string from a nested error structure
 * (`err.response.body.detail`). Returns undefined when absent.
 */
export declare function extractErrorDetail(err: unknown): string | undefined;