import { z } from 'zod/v4';
import { BaseError } from '@pawells/typescript-common';
/**
 * Zod schema for HTTP error metadata validation.
 * Extends base error metadata with an optional HTTP status code (100–599, per RFC 7231).
 *
 * @example
 * ```ts
 * const metadata = { code: 'NOT_FOUND', HTTPStatusCode: 404 };
 * HTTP_ERROR_METADATA_SCHEMA.parse(metadata); // validated
 * ```
 */
export declare const HTTP_ERROR_METADATA_SCHEMA: z.ZodObject<{
    code: z.ZodOptional<z.ZodString>;
    cause: z.ZodOptional<z.ZodCustom<Error, Error>>;
    HTTPStatusCode: z.ZodOptional<z.ZodNumber>;
}, z.core.$strip>;
/**
 * Inferred TypeScript type from HTTP_ERROR_METADATA_SCHEMA.
 * Represents validated HTTP error metadata.
 *
 * @example
 * ```ts
 * const metadata: THTTPErrorMetadata = {
 *   code: 'SERVER_ERROR',
 *   HTTPStatusCode: 500,
 *   cause: originalError
 * };
 * ```
 */
export type THTTPErrorMetadata = z.infer<typeof HTTP_ERROR_METADATA_SCHEMA>;
/**
 * Wraps ZodError in a domain-specific error class for HTTP metadata validation failures.
 *
 * @example
 * ```ts
 * try {
 *   AssertHTTPErrorMetadata(invalidMetadata);
 * } catch (error) {
 *   if (error instanceof HTTPMetadataValidationError) {
 *     console.error('Metadata validation failed:', error.message);
 *   }
 * }
 * ```
 */
export declare class HTTPMetadataValidationError extends BaseError<{
    code: string;
    cause?: Error;
}> {
    /**
     * Enumeration of metadata validation error codes for classification and debugging.
     *
     * - `VALIDATION_FAILED` — HTTP error metadata failed schema validation
     */
    static readonly Code: Readonly<{
        readonly VALIDATION_FAILED: "HTTP_METADATA_VALIDATION_ERROR";
    }>;
    /**
     * Creates a new HTTPMetadataValidationError.
     *
     * The error extends BaseError to provide structured error classification and cause chain propagation.
     * The code property is accessible via the `Code` getter (inherited from BaseError).
     * The cause chain is accessible via the `Cause` getter (inherited from BaseError).
     *
     * @param message - Human-readable error message
     * @param options - Optional configuration object
     * @param options.cause - The underlying ZodError from schema validation
     *
     * @example
     * ```ts
     * throw new HTTPMetadataValidationError(
     *   'Invalid HTTP metadata',
     *   { cause: zodError }
     * );
     * ```
     */
    constructor(message: string, options?: {
        cause?: Error;
    });
}
/**
 * Validates and asserts metadata conforms to HTTP_ERROR_METADATA_SCHEMA.
 * Throws HTTPMetadataValidationError if validation fails.
 *
 * @param metadata - Metadata to validate
 * @returns void — this is an assertion function that narrows the type to `THTTPErrorMetadata` on success or throws `HTTPMetadataValidationError` on failure
 * @throws {HTTPMetadataValidationError} If metadata fails schema validation
 *
 * @example
 * ```ts
 * AssertHTTPErrorMetadata({ code: 'TEST', HTTPStatusCode: 400 });
 * ```
 */
export declare function AssertHTTPErrorMetadata(metadata: unknown): asserts metadata is THTTPErrorMetadata;
/**
 * Validates metadata against HTTP_ERROR_METADATA_SCHEMA without throwing.
 * Returns true if valid, false otherwise.
 *
 * @param metadata - Metadata to validate
 * @returns true if metadata is valid, false otherwise
 *
 * @example
 * ```ts
 * if (ValidateHTTPErrorMetadata({ HTTPStatusCode: 404 })) {
 *   console.log('Valid');
 * }
 * ```
 */
export declare function ValidateHTTPErrorMetadata(metadata: unknown): boolean;
/**
 * Base class for HTTP error responses.
 * Extends BaseError with an optional HTTP status code.
 *
 * The HTTPStatusCode is typically set by subclasses for specific status codes.
 * The base HTTPError class keeps HTTPStatusCode optional/undefined as a generic escape hatch
 * for cases where the status code is not known at error construction time.
 *
 * @example
 * ```ts
 * try {
 * 	throw new HTTPError('Server error', { code: 'CUSTOM_ERROR', HTTPStatusCode: 502 });
 * } catch (error) {
 * 	if (error instanceof HTTPError) {
 * 		console.log(error.HTTPStatusCode); // 502
 * 	}
 * }
 * ```
 */
export declare class HTTPError extends BaseError<THTTPErrorMetadata> {
    /**
     * Returns the HTTP status code for this error.
     *
     * On the base HTTPError class, this may be undefined unless set explicitly via metadata.
     * Subclasses always return a specific status code — for example, HTTPNotFoundError always returns 404,
     * HTTPBadRequestError always returns 400, etc.
     *
     * @returns The HTTP status code (typically 100–599), or undefined if not set on the base class
     *
     * @example
     * ```ts
     * const error = new HTTPNotFoundError('Resource not found');
     * console.log(error.HTTPStatusCode); // 404
     * if (error.HTTPStatusCode === 404) {
     *   console.log('Not found error detected');
     * }
     * ```
     *
     * @example
     * ```ts
     * // Base class with no status code set
     * const error = new HTTPError('Generic error', { code: 'GENERIC_ERROR' });
     * console.log(error.HTTPStatusCode); // undefined
     * ```
     */
    get HTTPStatusCode(): number | undefined;
    /**
     * Creates a new HTTPError.
     *
     * @param message - Human-readable error message
     * @param metadata - HTTP error metadata (partial); validated and merged with defaults on construction
     * @throws {HTTPMetadataValidationError} If metadata fails schema validation
     *
     * @example
     * ```ts
     * const error = new HTTPError('Server error', {
     * 	code: 'SERVER_ERROR',
     * 	HTTPStatusCode: 500,
     * 	cause: new Error('Database unavailable')
     * });
     * throw error;
     * ```
     */
    constructor(message: string, metadata: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 400 Bad Request error.
 * The server cannot or will not process the request due to client error.
 *
 * @example
 * ```ts
 * throw new HTTPBadRequestError('Invalid email format', {
 *   cause: new Error('Failed to parse email'),
 * });
 * ```
 */
export declare class HTTPBadRequestError extends HTTPError {
    /**
     * Creates a new HTTPBadRequestError (400).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPBadRequestError('Missing required field: email');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPBadRequestError('Invalid input', {
     *   cause: new ZodError([])
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 401 Unauthorized error.
 * Authentication is required and has failed or has not been provided.
 *
 * @example
 * ```ts
 * throw new HTTPUnauthorizedError('Missing authentication token', {
 *   cause: new Error('No Authorization header'),
 * });
 * ```
 */
export declare class HTTPUnauthorizedError extends HTTPError {
    /**
     * Creates a new HTTPUnauthorizedError (401).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPUnauthorizedError('Authentication token expired');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPUnauthorizedError('Invalid credentials', {
     *   cause: new Error('Token verification failed')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 403 Forbidden error.
 * The request is understood, but server refuses to fulfill it.
 *
 * @example
 * ```ts
 * throw new HTTPForbiddenError('Access denied to resource', {
 *   cause: new Error('User lacks required permissions'),
 * });
 * ```
 */
export declare class HTTPForbiddenError extends HTTPError {
    /**
     * Creates a new HTTPForbiddenError (403).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPForbiddenError('You do not have permission to access this resource');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPForbiddenError('Access denied', {
     *   cause: new Error('Missing required role')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 404 Not Found error.
 * The requested resource could not be found on the server.
 *
 * @example
 * ```ts
 * throw new HTTPNotFoundError('User profile not found', {
 *   cause: new Error('User ID 123 does not exist'),
 * });
 * ```
 */
export declare class HTTPNotFoundError extends HTTPError {
    /**
     * Creates a new HTTPNotFoundError (404).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPNotFoundError('Page not found');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPNotFoundError('Resource not found', {
     *   cause: new Error('Database lookup failed')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 405 Method Not Allowed error.
 * The HTTP method used is not supported by the resource.
 *
 * @example
 * ```ts
 * throw new HTTPMethodNotAllowedError('PUT method not allowed', {
 *   cause: new Error('Resource is read-only'),
 * });
 * ```
 */
export declare class HTTPMethodNotAllowedError extends HTTPError {
    /**
     * Creates a new HTTPMethodNotAllowedError (405).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPMethodNotAllowedError('DELETE method not allowed for this resource');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPMethodNotAllowedError('Method not supported', {
     *   cause: new Error('Only GET is allowed')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 406 Not Acceptable error.
 * The server cannot produce a response matching the list of acceptable values defined in the request's proactive content negotiation headers.
 *
 * @example
 * ```ts
 * throw new HTTPNotAcceptableError('No acceptable content type available', {
 *   cause: new Error('Client requires image/webp but only image/jpeg available'),
 * });
 * ```
 */
export declare class HTTPNotAcceptableError extends HTTPError {
    /**
     * Creates a new HTTPNotAcceptableError (406).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPNotAcceptableError('Requested content type not available');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPNotAcceptableError('Not acceptable', {
     *   cause: new Error('Accept header mismatch')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 409 Conflict error.
 * The request conflicts with the current state of the server.
 *
 * @example
 * ```ts
 * throw new HTTPConflictError('Resource version mismatch', {
 *   cause: new Error('ETag does not match'),
 * });
 * ```
 */
export declare class HTTPConflictError extends HTTPError {
    /**
     * Creates a new HTTPConflictError (409).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPConflictError('Username already exists');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPConflictError('Conflict detected', {
     *   cause: new Error('Concurrent modification detected')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 408 Request Timeout error.
 * The server timed out waiting for the request from the client.
 *
 * @example
 * ```ts
 * throw new HTTPRequestTimeoutError('Request took too long', {
 *   cause: new Error('Client did not complete request in time'),
 * });
 * ```
 */
export declare class HTTPRequestTimeoutError extends HTTPError {
    /**
     * Creates a new HTTPRequestTimeoutError (408).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPRequestTimeoutError('Request timeout');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPRequestTimeoutError('Client timeout', {
     *   cause: new Error('No data received within 30s')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 410 Gone error.
 * The requested resource is no longer available and will not be available again.
 * This differs from a 404 (Not Found) because the resource existed but is now gone permanently.
 *
 * @example
 * ```ts
 * throw new HTTPGoneError('Resource has been permanently removed', {
 *   cause: new Error('Content deleted by user'),
 * });
 * ```
 */
export declare class HTTPGoneError extends HTTPError {
    /**
     * Creates a new HTTPGoneError (410).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPGoneError('This resource is no longer available');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPGoneError('Resource gone', {
     *   cause: new Error('Content was permanently deleted')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 413 Payload Too Large error.
 * The request entity is larger than limits defined by the server; the server might close the connection or return a Retry-After header.
 *
 * @example
 * ```ts
 * throw new HTTPPayloadTooLargeError('File upload exceeds maximum size', {
 *   cause: new Error('File size 100MB exceeds limit of 10MB'),
 * });
 * ```
 */
export declare class HTTPPayloadTooLargeError extends HTTPError {
    /**
     * Creates a new HTTPPayloadTooLargeError (413).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPPayloadTooLargeError('Request body too large');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPPayloadTooLargeError('Payload too large', {
     *   cause: new Error('Content-Length exceeds max')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 415 Unsupported Media Type error.
 * The request entity has a media type which the server does not support.
 *
 * @example
 * ```ts
 * throw new HTTPUnsupportedMediaTypeError('Expected JSON but received XML', {
 *   cause: new Error('Content-Type: application/xml not supported'),
 * });
 * ```
 */
export declare class HTTPUnsupportedMediaTypeError extends HTTPError {
    /**
     * Creates a new HTTPUnsupportedMediaTypeError (415).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPUnsupportedMediaTypeError('This endpoint only accepts application/json');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPUnsupportedMediaTypeError('Unsupported media type', {
     *   cause: new Error('Content-Type header invalid')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 422 Unprocessable Entity error.
 * The request was well-formed but contains semantic errors.
 *
 * @example
 * ```ts
 * throw new HTTPUnprocessableEntityError('Validation failed', {
 *   cause: new Error('Missing required field: email'),
 * });
 * ```
 */
export declare class HTTPUnprocessableEntityError extends HTTPError {
    /**
     * Creates a new HTTPUnprocessableEntityError (422).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPUnprocessableEntityError('Email address is invalid');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPUnprocessableEntityError('Validation error', {
     *   cause: new ZodError([])
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 429 Too Many Requests error.
 * The user has sent too many requests in a given amount of time (rate limiting).
 *
 * @example
 * ```ts
 * throw new HTTPTooManyRequestsError('Rate limit exceeded', {
 *   cause: new Error('100 requests per minute limit exceeded'),
 * });
 * ```
 */
export declare class HTTPTooManyRequestsError extends HTTPError {
    /**
     * The Retry-After value, if provided.
     * Per RFC 7231 section 7.1.3, this can be either:
     * - A number representing delay in seconds (non-negative integer)
     * - A Date object representing the HTTP-date when retry should be attempted
     */
    private readonly retryAfter?;
    /**
     * Returns the Retry-After delay or HTTP-date for this error.
     * Useful for implementing client-side retry logic with backoff.
     *
     * @returns The Retry-After value (number of seconds or Date), or undefined if not set
     *
     * @example
     * ```ts
     * const error = new HTTPTooManyRequestsError('Rate limited', { retryAfter: 60 });
     * if (error.RetryAfter !== undefined) {
     *   if (typeof error.RetryAfter === 'number') {
     *     console.log(`Retry after ${error.RetryAfter} seconds`);
     *   } else {
     *     console.log(`Retry after ${error.RetryAfter.toISOString()}`);
     *   }
     * }
     * ```
     */
    get RetryAfter(): number | Date | undefined;
    /**
     * Creates a new HTTPTooManyRequestsError (429).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain and retryAfter
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPTooManyRequestsError('Too many login attempts. Please try again later.');
     * ```
     *
     * @example
     * ```ts
     * // Retry after 60 seconds (RFC 7231 delay-seconds form)
     * throw new HTTPTooManyRequestsError('Rate limited', {
     *   retryAfter: 60,
     *   cause: new Error('Exceeded quota')
     * });
     * ```
     *
     * @example
     * ```ts
     * // Retry after HTTP-date (RFC 7231 HTTP-date form)
     * const retryDate = new Date(Date.now() + 3600000); // 1 hour from now
     * throw new HTTPTooManyRequestsError('Rate limited', {
     *   retryAfter: retryDate,
     *   cause: new Error('Exceeded quota')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata> & {
        retryAfter?: number | Date;
    });
}
/**
 * Represents an HTTP 451 Unavailable For Legal Reasons error.
 * The server cannot provide the requested resource due to legal reasons, such as censorship or government-mandated content filtering.
 *
 * @example
 * ```ts
 * throw new HTTPUnavailableForLegalReasonsError('Content not available in your region', {
 *   cause: new Error('Content blocked by government regulation'),
 * });
 * ```
 */
export declare class HTTPUnavailableForLegalReasonsError extends HTTPError {
    /**
     * Creates a new HTTPUnavailableForLegalReasonsError (451).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPUnavailableForLegalReasonsError('This content is not available in your jurisdiction');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPUnavailableForLegalReasonsError('Unavailable for legal reasons', {
     *   cause: new Error('Legal hold on content')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 500 Internal Server Error.
 * The server encountered an unexpected condition that prevented it from fulfilling the request.
 *
 * @example
 * ```ts
 * throw new HTTPInternalServerError('Database connection failed', {
 *   cause: new Error('Connection timeout'),
 * });
 * ```
 */
export declare class HTTPInternalServerError extends HTTPError {
    /**
     * Creates a new HTTPInternalServerError (500).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPInternalServerError('An unexpected error occurred while processing your request');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPInternalServerError('Server error', {
     *   cause: new Error('Database unavailable')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 501 Not Implemented error.
 * The server does not support the functionality required to fulfill the request.
 *
 * @example
 * ```ts
 * throw new HTTPNotImplementedError('WebSocket not supported', {
 *   cause: new Error('WebSocket handler not configured'),
 * });
 * ```
 */
export declare class HTTPNotImplementedError extends HTTPError {
    /**
     * Creates a new HTTPNotImplementedError (501).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPNotImplementedError('This feature is not yet implemented');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPNotImplementedError('Feature not available', {
     *   cause: new Error('Implementation pending')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 502 Bad Gateway error.
 * The server received an invalid response from an upstream server.
 *
 * @example
 * ```ts
 * throw new HTTPBadGatewayError('Upstream server error', {
 *   cause: new Error('Gateway received 500 from upstream'),
 * });
 * ```
 */
export declare class HTTPBadGatewayError extends HTTPError {
    /**
     * Creates a new HTTPBadGatewayError (502).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPBadGatewayError('Bad gateway: upstream server is not responding correctly');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPBadGatewayError('Gateway error', {
     *   cause: new Error('Upstream service unavailable')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Represents an HTTP 503 Service Unavailable error.
 * The server is temporarily unable to handle the request, usually due to maintenance or overload.
 *
 * @example
 * ```ts
 * throw new HTTPServiceUnavailableError('Server is down for maintenance', {
 *   cause: new Error('Maintenance window active'),
 * });
 * ```
 */
export declare class HTTPServiceUnavailableError extends HTTPError {
    /**
     * The Retry-After value, if provided.
     * Per RFC 7231 section 7.1.3, this can be either:
     * - A number representing delay in seconds (non-negative integer)
     * - A Date object representing the HTTP-date when retry should be attempted
     */
    private readonly retryAfter?;
    /**
     * Returns the Retry-After delay or HTTP-date for this error.
     * Useful for implementing client-side retry logic with backoff.
     *
     * @returns The Retry-After value (number of seconds or Date), or undefined if not set
     *
     * @example
     * ```ts
     * const error = new HTTPServiceUnavailableError('Service unavailable', { retryAfter: 120 });
     * if (error.RetryAfter !== undefined) {
     *   if (typeof error.RetryAfter === 'number') {
     *     console.log(`Retry after ${error.RetryAfter} seconds`);
     *   } else {
     *     console.log(`Retry after ${error.RetryAfter.toISOString()}`);
     *   }
     * }
     * ```
     */
    get RetryAfter(): number | Date | undefined;
    /**
     * Creates a new HTTPServiceUnavailableError (503).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain and retryAfter
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPServiceUnavailableError('The service is temporarily unavailable. Please try again later.');
     * ```
     *
     * @example
     * ```ts
     * // Retry after 120 seconds (RFC 7231 delay-seconds form)
     * throw new HTTPServiceUnavailableError('Service down', {
     *   retryAfter: 120,
     *   cause: new Error('Server overloaded')
     * });
     * ```
     *
     * @example
     * ```ts
     * // Retry after HTTP-date (RFC 7231 HTTP-date form)
     * const retryDate = new Date(Date.now() + 1800000); // 30 minutes from now
     * throw new HTTPServiceUnavailableError('Service down', {
     *   retryAfter: retryDate,
     *   cause: new Error('Maintenance window')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata> & {
        retryAfter?: number | Date;
    });
}
/**
 * Represents an HTTP 504 Gateway Timeout error.
 * The server did not receive a timely response from an upstream server.
 *
 * @example
 * ```ts
 * throw new HTTPGatewayTimeoutError('Upstream timeout', {
 *   cause: new Error('Gateway timeout after 60s'),
 * });
 * ```
 */
export declare class HTTPGatewayTimeoutError extends HTTPError {
    /**
     * Creates a new HTTPGatewayTimeoutError (504).
     *
     * @param message - Human-readable error message
     * @param metadata - Optional error metadata with cause chain
     * @throws {HTTPMetadataValidationError} If metadata fails validation
     *
     * @example
     * ```ts
     * throw new HTTPGatewayTimeoutError('Gateway timeout: upstream server did not respond in time');
     * ```
     *
     * @example
     * ```ts
     * throw new HTTPGatewayTimeoutError('Timeout', {
     *   cause: new Error('Upstream timeout after 30s')
     * });
     * ```
     */
    constructor(message: string, metadata?: Partial<THTTPErrorMetadata>);
}
/**
 * Union type of all HTTP error class constructors.
 *
 * @example
 * ```ts
 * const ErrorClass: THTTPErrorClasses = HTTPBadRequestError;
 * ```
 */
export type THTTPErrorClasses = typeof HTTPBadRequestError | typeof HTTPUnauthorizedError | typeof HTTPForbiddenError | typeof HTTPNotFoundError | typeof HTTPMethodNotAllowedError | typeof HTTPNotAcceptableError | typeof HTTPRequestTimeoutError | typeof HTTPGoneError | typeof HTTPConflictError | typeof HTTPPayloadTooLargeError | typeof HTTPUnsupportedMediaTypeError | typeof HTTPUnprocessableEntityError | typeof HTTPTooManyRequestsError | typeof HTTPUnavailableForLegalReasonsError | typeof HTTPInternalServerError | typeof HTTPNotImplementedError | typeof HTTPBadGatewayError | typeof HTTPServiceUnavailableError | typeof HTTPGatewayTimeoutError;
/**
 * Immutable mapping of HTTP status codes to error class constructors.
 * Frozen at module load time via `Object.freeze()` to prevent runtime mutations
 * that could break error handling. Attempts to mutate (add, modify, or delete properties)
 * throw a TypeError in strict mode (which includes all ESM modules).
 *
 * Maps the 19 concrete error classes to their HTTP status codes:
 * 400, 401, 403, 404, 405, 406, 408, 409, 410, 413, 415, 422, 429, 451, 500, 501, 502, 503, 504.
 *
 * @example
 * ```ts
 * const ErrorClass = HTTP_ERROR_CLASS_MAP[404];
 * if (ErrorClass) {
 *   throw new ErrorClass('Not found');
 * }
 * ```
 *
 * @example
 * ```ts
 * // Attempting to modify throws TypeError in strict mode
 * HTTP_ERROR_CLASS_MAP[418] = HTTPBadRequestError; // Throws TypeError
 * ```
 */
export declare const HTTP_ERROR_CLASS_MAP: Readonly<Partial<Record<number, THTTPErrorClasses>>>;
/**
 * Returns the appropriate HTTPError subclass for the given HTTP status code.
 *
 * @param statusCode - The HTTP status code to look up
 * @returns The error class constructor for the status code, or `undefined` if not mapped
 *
 * @example
 * ```ts
 * const ErrorClass = GetHTTPErrorClass(404);
 * if (ErrorClass) {
 *   throw new ErrorClass('Resource not found');
 * }
 * ```
 */
export declare function GetHTTPErrorClass(statusCode: number): THTTPErrorClasses | undefined;
/**
 * Throws an HTTP error for the given status code.
 *
 * Looks up the appropriate `HTTPError` subclass using `GetHTTPErrorClass`, instantiates it with the provided message and metadata, and throws it.
 * For unmapped status codes (e.g., 200, 301, 418), throws a generic `HTTPError` with the status code in metadata.
 * For out-of-range status codes (outside 100–599, per RFC 7231), throws `HTTPMetadataValidationError` during metadata validation.
 *
 * This function always throws — the return type is `never`.
 *
 * @param statusCode - The HTTP status code that identifies the error type (must be 100–599 per RFC 7231, or will throw during validation)
 * @param message - Human-readable error message
 * @param metadata - Optional error metadata (cause chain, custom code)
 * @returns Never — this function always throws
 * @throws {HTTPBadRequestError | HTTPUnauthorizedError | HTTPForbiddenError | HTTPNotFoundError | HTTPMethodNotAllowedError | HTTPNotAcceptableError | HTTPRequestTimeoutError | HTTPConflictError | HTTPGoneError | HTTPPayloadTooLargeError | HTTPUnsupportedMediaTypeError | HTTPUnprocessableEntityError | HTTPTooManyRequestsError | HTTPUnavailableForLegalReasonsError | HTTPInternalServerError | HTTPNotImplementedError | HTTPBadGatewayError | HTTPServiceUnavailableError | HTTPGatewayTimeoutError | HTTPError} Throws the appropriate error subclass for the status code, or a generic HTTPError if unmapped
 * @throws {HTTPMetadataValidationError} If statusCode is outside the valid range (100–599)
 *
 * @example
 * ```ts
 * // Throws HTTPNotFoundError (404)
 * ThrowHTTPError(404, 'User not found');
 * ```
 *
 * @example
 * ```ts
 * // Throws HTTPBadRequestError (400) with cause chain
 * try {
 *   const data = parseJSON(raw);
 * } catch (cause) {
 *   ThrowHTTPError(400, 'Invalid JSON payload', { cause });
 * }
 * ```
 *
 * @example
 * ```ts
 * // Throws generic HTTPError for unmapped status code (418)
 * ThrowHTTPError(418, 'I am a teapot');
 * ```
 *
 * @example
 * ```ts
 * // Throws HTTPMetadataValidationError for out-of-range status code
 * ThrowHTTPError(700, 'Out of range');
 * ```
 */
export declare function ThrowHTTPError(statusCode: number, message: string, metadata?: Partial<THTTPErrorMetadata>): never;
//# sourceMappingURL=http-errors.d.ts.map