@belgattitude/http-exception/dist/types/index.d.ts

Warning: has been moved to @httpx/exception. Please update.

type HttpExceptionParams = {
    /**
     * Exception message, if not provided the default is the exception
     * name in natural language (ie: "HttpNotFound" -> "Not found")
     */
    message?: string;
    /**
     * Indicates the original url that caused the error.
     */
    url?: string;
    /**
     * Inform about http method
     */
    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH';
    /**
     * Custom additional code (ie: 'AbortError', 'CODE-1234'...)
     */
    code?: string;
    /**
     * Inform about an unique error identifier (ie: nanoid, cuid...)
     */
    errorId?: string;
    /**
     * Indicates the original cause of the HttpException.
     * Will be ignored/discarded if the runtime (browser / node version) does not support it
     * or there's no polyfill
     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
     */
    cause?: Error;
};

type HttpStatusCode = number;

type HttpExceptionParamsWithStatus = HttpExceptionParams & {
    statusCode: HttpStatusCode;
};

type HttpMethod = 'GET' | 'HEAD' | 'POST' | 'PUT' | 'DELETE' | 'CONNECT' | 'OPTIONS' | 'TRACE' | 'PATCH';

declare class HttpException extends Error {
    /**
     * Http error status code (400-599)
     */
    readonly statusCode: number;
    /**
     * Indicates the original url that caused the error.
     */
    readonly url: string | undefined;
    /**
     * Http method
     */
    readonly method: HttpMethod | undefined;
    /**
     * Custom additional code (ie: 'AbortError', 'CODE-1234'...)
     */
    readonly code: string | undefined;
    /**
     * Inform about an unique error identifier (ie: nanoid, cuid...)
     */
    readonly errorId: string | undefined;
    /**
     * If set and the runtime (browser or node) supports it
     * you can get back the error cause
     * @see https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error/cause
     */
    readonly cause?: Error | HttpException;
    /**
     * Construct a new HttpException class
     *
     * @param statusCode http status code between 400-599, no checks are done on the validity of the number.
     * @param msgOrParams either a message or an object containing HttpExceptionParams
     */
    constructor(statusCode: number, msgOrParams?: HttpExceptionParams | string);
}

/**
 * Construct a new HttpServerException class
 *
 * @param statusCode http status code between 500-599, no checks are done on the validity of the number.
 * @param msgOrParams either a message or an object containing HttpExceptionParams
 */
declare class HttpServerException extends HttpException {
    constructor(statusCode: number, msgOrParams?: HttpExceptionParams | string);
}

/**
 * Construct a new HttpClientException class
 *
 * @param statusCode http status code between 400-499, no checks are done on the validity of the number.
 * @param msgOrParams either a message or an object containing HttpExceptionParams
 */
declare class HttpClientException extends HttpException {
    constructor(statusCode: number, msgOrParams?: HttpExceptionParams | string);
}

/**
 * 400 Bad Request (client)
 *
 * The server cannot or will not process the request due to something that is perceived to be a client error
 * (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
 *
 * @see https://httpstatus.in/400/
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/400
 */
declare class HttpBadRequest extends HttpClientException {
    static readonly STATUS = 400;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 409 Conflict (client)
 *
 * This response is sent when a request conflicts with the current state of the server.
 *
 * @see https://httpstatus.in/409/
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/409
 */
declare class HttpConflict extends HttpClientException {
    static readonly STATUS = 409;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * Client status 417
 *
 * The HTTP 417 Expectation Failed client error response code indicates that the expectation given
 * in the request's Expect header could not be met.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/417
 * @see https://httpstatus.in/417/
 */
declare class HttpExpectationFailed extends HttpClientException {
    static readonly STATUS = 417;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 424 Failed dependency (client / webdav specific)
 *
 * The method could not be performed on the resource because the requested action depended on another action
 * and that action failed.
 *
 * For example, if a command in a PROPPATCH method fails, then, at minimum, the rest of the commands will
 * also fail with 424 Failed Dependency.
 *
 * @see https://httpstatus.in/424/
 */
declare class HttpFailedDependency extends HttpClientException {
    static readonly STATUS = 424;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 403 Forbidden (client)
 *
 * The client does not have access rights to the content; that is, it is unauthorized, so the server
 * is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/403
 * @see https://httpstatus.in/403/
 */
declare class HttpForbidden extends HttpClientException {
    static readonly STATUS = 403;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 410 Gone (client)
 *
 * This response is sent when the requested content has been permanently deleted from server, with no forwarding address.
 * Clients are expected to remove their caches and links to the resource. The HTTP specification intends
 * this status code to be used for "limited-time, promotional services".
 *
 * APIs should not feel compelled to indicate resources that have been deleted with this status code.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/410
 * @see https://httpstatus.in/410/
 */
declare class HttpGone extends HttpClientException {
    static readonly STATUS = 410;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 418 I'm a teapot (client)
 *
 * The server refuses the attempt to brew coffee with a teapot.
 *
 * @see https://httpstatus.in/418/
 * @link https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/418
 */
declare class HttpImATeapot extends HttpClientException {
    static readonly STATUS = 418;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 411 Length required
 *
 * Server rejected the request because the Content-Length header field is not defined and the server requires it.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/411
 * @see https://httpstatus.in/411/
 */
declare class HttpLengthRequired extends HttpClientException {
    static readonly STATUS = 411;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 423 Locked (client / webdav specific)
 *
 * The source or destination resource of a method is locked. This response SHOULD contain an
 * appropriate precondition or postcondition code, such as ‘lock-token-submitted’ or ‘no-conflicting-lock’.
 *
 * @see https://httpstatus.in/423/
 */
declare class HttpLocked extends HttpClientException {
    static readonly STATUS = 423;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 421 Misdirected Request (client)
 *
 * The request was directed at a server that is not able to produce a response. This can be sent by a server that
 * is not configured to produce responses for the combination of scheme and authority that are included
 * in the request URI.
 *
 * @see https://httpstatus.in/421/
 */
declare class HttpMisdirectedRequest extends HttpClientException {
    static readonly STATUS = 421;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 405 Method not allowed (client)
 *
 * The request method is known by the server but is not supported by the target resource.
 * For example, an API may not allow calling DELETE to remove a resource.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/405
 * @see https://httpstatus.in/405/
 */
declare class HttpMethodNotAllowed extends HttpClientException {
    static readonly STATUS = 405;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 406 Not acceptable (client)
 *
 * This response is sent when the web server, after performing server-driven content negotiation, doesn't find
 * any content that conforms to the criteria given by the user agent.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/406
 * @see https://httpstatus.in/406/
 */
declare class HttpNotAcceptable extends HttpClientException {
    static readonly STATUS = 406;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 404 - Not found (client)
 *
 * The server can not find the requested resource. In the browser, this means the URL is not recognized.
 * In an API, this can also mean that the endpoint is valid but the resource itself does not exist.
 * Servers may also send this response instead of 403 Forbidden to hide the existence of a resource from an
 * unauthorized client.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/404
 * @see https://httpstatus.in/404/
 */
declare class HttpNotFound extends HttpClientException {
    static readonly STATUS = 404;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 413 Payload too large (client)
 *
 * Request entity is larger than limits defined by server. The server might close the connection or return an Retry-After header field.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/413
 * @see https://httpstatus.in/413/
 */
declare class HttpPayloadTooLarge extends HttpClientException {
    static readonly STATUS = 413;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 402 Payment required (client)
 *
 * This response code is reserved for future use. The initial aim for creating this code was using it for digital
 * payment systems, however this status code is used very rarely and no standard convention exists.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/402
 * @see https://httpstatus.in/402/
 */
declare class HttpPaymentRequired extends HttpClientException {
    static readonly STATUS = 402;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 412 Precondition Failed (client)
 *
 * The client has indicated preconditions in its headers which the server does not meet.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/412
 * @see https://httpstatus.in/412/
 */
declare class HttpPreconditionFailed extends HttpClientException {
    static readonly STATUS = 412;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 428 Precondition Required (client)
 *
 * The origin server requires the request to be conditional. This response is intended to prevent the
 * 'lost update' problem, where a client GETs a resource's state, modifies it and PUTs it back to the
 * server, when meanwhile a third party has modified the state on the server, leading to a conflict.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/428
 * @see https://httpstatus.in/428/
 */
declare class HttpPreconditionRequired extends HttpClientException {
    static readonly STATUS = 428;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 407 Proxy authentication required (client)
 *
 * This is similar to 401 Unauthorized but authentication is needed to be done by a proxy
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/407
 * @see https://httpstatus.in/407/
 */
declare class HttpProxyAuthenticationRequired extends HttpClientException {
    static readonly STATUS = 407;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 416 Range Not Satisfiable (client)
 *
 * The range specified by the Range header field in the request cannot be fulfilled.
 * It's possible that the range is outside the size of the target URI's data.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/416
 * @see https://httpstatus.in/416/
 */
declare class HttpRangeNotSatisfiable extends HttpClientException {
    static readonly STATUS = 416;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 431 Request Header Fields Too Large (client)
 *
 * The server is unwilling to process the request because its header fields are too large.
 * The request may be resubmitted after reducing the size of the request header fields.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/431
 * @see https://httpstatus.in/431/
 */
declare class HttpRequestHeaderFieldsTooLarge extends HttpClientException {
    static readonly STATUS = 431;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 408 Request timeout (client)
 *
 * This response is sent on an idle connection by some servers, even without any previous request by the client.
 * It means that the server would like to shut down this unused connection. This response is used much more
 * since some browsers, like Chrome, Firefox 27+, or IE9, use HTTP pre-connection mechanisms to speed up surfing.
 * Also note that some servers merely shut down the connection without sending this message.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/408
 * @see https://httpstatus.in/408/
 */
declare class HttpRequestTimeout extends HttpClientException {
    static readonly STATUS = 408;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 425 Too early (client / experimental)
 *
 * Indicates that the server is unwilling to risk processing a request that might be replayed.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/425
 */
declare class HttpTooEarly extends HttpClientException {
    static readonly STATUS = 425;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 429 Too Many Requests (client)
 *
 * The user has sent too many requests in a given amount of time ("rate limiting").
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/429
 * @see https://httpstatus.in/429/
 */
declare class HttpTooManyRequests extends HttpClientException {
    static readonly STATUS = 429;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 401 Unauthorized (client)
 *
 * Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated".
 * That is, the client must authenticate itself to get the requested response.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401
 * @see https://httpstatus.in/401/
 */
declare class HttpUnauthorized extends HttpClientException {
    static readonly STATUS = 401;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 451 Unavailable For Legal Reasons (client)
 *
 * The user agent requested a resource that cannot legally be provided, such as a web page censored by a government.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/451
 * @see https://httpstatus.in/451/
 */
declare class HttpUnavailableForLegalReasons extends HttpClientException {
    static readonly STATUS = 451;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 422 Unprocessable entity (client / webdav specific)
 *
 * The server understands the content type of the request entity (hence a 415 Unsupported Media Type status code
 * is inappropriate), and the syntax of the request entity is correct (thus a 400 Bad Request status code is
 * inappropriate) but was unable to process the contained instructions.
 *
 * For example, this error condition may occur if an XML request body contains well-formed
 * (i.e., syntactically correct), but semantically erroneous, XML instructions.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/422
 * @see https://httpstatus.in/422/
 */
declare class HttpUnprocessableEntity extends HttpClientException {
    static readonly STATUS = 422;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 415 Unsupported Media Type (client)
 *
 * The media format of the requested data is not supported by the server, so the server is rejecting the request.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/415
 * @see https://httpstatus.in/415/
 */
declare class HttpUnsupportedMediaType extends HttpClientException {
    static readonly STATUS = 415;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 426 Upgrade Required (client)
 *
 * The server refuses to perform the request using the current protocol but might be willing to do so after
 * the client upgrades to a different protocol. The server sends an Upgrade header in a 426 response
 * to indicate the required protocol(s).
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/426
 */
declare class HttpUpgradeRequired extends HttpClientException {
    static readonly STATUS = 426;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 414 URI too long (client)
 *
 * The URI requested by the client is longer than the server is willing to interpret.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/414
 * @see https://httpstatus.in/414/
 */
declare class HttpUriTooLong extends HttpClientException {
    static readonly STATUS = 414;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 502 Bad Gateway (server)
 *
 * This error response means that the server, while working as a gateway to get a response needed to
 * handle the request, got an invalid response.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/502
 */
declare class HttpBadGateway extends HttpServerException {
    static readonly STATUS = 502;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 505 HTTP Version Not Supported
 *
 * The HTTP version used in the request is not supported by the server.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/505
 * @see https://httpstatus.in/505/
 */
declare class HttpVersionNotSupported extends HttpServerException {
    static readonly STATUS = 505;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 504 Gateway Timeout (server)
 *
 * This error response is given when the server is acting as a gateway and cannot get a response in time.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/504
 * @see https://httpstatus.in/504/
 */
declare class HttpGatewayTimeout extends HttpServerException {
    static readonly STATUS = 504;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 500 Internal Server Error (server)
 *
 * The server has encountered a situation it does not know how to handle.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/500
 * @see https://httpstatus.in/500/
 */
declare class HttpInternalServerError extends HttpServerException {
    static readonly STATUS = 500;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 511 Network Authentication Required (server)
 *
 * Indicates that the client needs to authenticate to gain network access.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/511
 * @see https://httpstatus.in/511/
 */
declare class HttpNetworkAuthenticationRequired extends HttpServerException {
    static readonly STATUS = 511;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 510 Not Extended (server)
 *
 * Further extensions to the request are required for the server to fulfill it.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/510
 * @see https://httpstatus.in/510/
 */
declare class HttpNotExtended extends HttpServerException {
    static readonly STATUS = 510;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 501 Not Implemented
 *
 * The request method is not supported by the server and cannot be handled. The only methods that
 * servers are required to support (and therefore that must not return this code) are GET and HEAD.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/501
 * @see https://httpstatus.in/501/
 */
declare class HttpNotImplemented extends HttpServerException {
    static readonly STATUS = 501;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 503 Service Unavailable
 *
 * The server is not ready to handle the request. Common causes are a server that is down for maintenance
 * or that is overloaded. Note that together with this response, a user-friendly page explaining the problem
 * should be sent.
 *
 * This response should be used for temporary conditions and the Retry-After HTTP header should, if possible,
 * contain the estimated time before the recovery of the service. The webmaster must also take care about the
 * caching-related headers that are sent along with this response, as these temporary condition responses
 * should usually not be cached.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/503
 * @see https://httpstatus.in/503/
 */
declare class HttpServiceUnavailable extends HttpServerException {
    static readonly STATUS = 503;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 507 Insufficient Storage (client / webdav specific)
 *
 * The method could not be performed on the resource because the server is unable to store the representation
 * needed to successfully complete the request.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/507
 */
declare class HttpInsufficientStorage extends HttpServerException {
    static readonly STATUS = 507;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 508 Loop Detected (server / webdav specific)
 *
 * The server detected an infinite loop while processing the request.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/508
 * @see https://httpstatus.in/508/
 */
declare class HttpLoopDetected extends HttpServerException {
    static readonly STATUS = 508;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

/**
 * 506 Variant Also Negotiates (server)
 *
 * The server has an internal configuration error: the chosen variant resource is configured to engage
 * in transparent content negotiation itself, and is therefore not a proper end point in the negotiation process.
 *
 * @see https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/506
 * @see https://httpstatus.in/506/
 */
declare class HttpVariantAlsoNegotiates extends HttpServerException {
    static readonly STATUS = 506;
    constructor(msgOrParams?: HttpExceptionParams | string);
}

declare const isHttpException: (error: unknown) => error is HttpException;

declare const isHttpClientException: (error: unknown) => error is HttpClientException;

declare const isHttpServerException: (error: unknown) => error is HttpServerException;

/**
 * Check if the provided value is a valid http status code
 */
declare const isHttpStatusCode: (statusCode: unknown) => statusCode is number;

/**
 * Check if the provided value is a valid http status code
 */
declare const isHttpErrorStatusCode: <T extends number = number>(statusCode: unknown) => statusCode is T;

/**
 * Create a concrete http exception object from a given http status code.
 *
 * If the status does not have an assigned ietf class, it will default
 * to either HttpClientException or HttpServerException based on ranges
 * (client: 400-499, server: 500-599).
 *
 * At last resort, if the provided status does not meet error range requirements
 * (400-599), it will create an HttpException with the out-of-scope code (ie: 100, 300, 1099...)
 *
 * @param statusCode http status code between 400-599
 * @param msgOrParams either a message or an object containing HttpExceptionParams
 */
declare const createHttpException: (statusCode: number, msgOrParams?: string | HttpExceptionParams) => HttpException | HttpServerException | HttpClientException;

export { HttpBadGateway, HttpBadRequest, HttpClientException, HttpConflict, HttpException, HttpExceptionParams, HttpExceptionParamsWithStatus, HttpExpectationFailed, HttpFailedDependency, HttpForbidden, HttpGatewayTimeout, HttpGone, HttpImATeapot, HttpInsufficientStorage, HttpInternalServerError, HttpLengthRequired, HttpLocked, HttpLoopDetected, HttpMethodNotAllowed, HttpMisdirectedRequest, HttpNetworkAuthenticationRequired, HttpNotAcceptable, HttpNotExtended, HttpNotFound, HttpNotImplemented, HttpPayloadTooLarge, HttpPaymentRequired, HttpPreconditionFailed, HttpPreconditionRequired, HttpProxyAuthenticationRequired, HttpRangeNotSatisfiable, HttpRequestHeaderFieldsTooLarge, HttpRequestTimeout, HttpServerException, HttpServiceUnavailable, HttpStatusCode, HttpTooEarly, HttpTooManyRequests, HttpUnauthorized, HttpUnavailableForLegalReasons, HttpUnprocessableEntity, HttpUnsupportedMediaType, HttpUpgradeRequired, HttpUriTooLong, HttpVariantAlsoNegotiates, HttpVersionNotSupported, createHttpException, isHttpClientException, isHttpErrorStatusCode, isHttpException, isHttpServerException, isHttpStatusCode };