http-eaas

Sarcastic HTTP status messages for developers who've seen one too many 404 Not Found strings.

What is this?

http-eaas is a zero-dependency TypeScript library that returns a randomly selected sarcastic, deadpan excuse message for a given HTTP status code. Instead of showing users 404 Not Found — which tells them nothing and entertains no one — you get messages like:

"Yeah it's gone. Shocking, I know. Try not to spiral."

It exists because default HTTP error strings are boring, and your error pages don't have to be. The voice is dry, resigned, and a little tired — like a senior engineer on a Friday afternoon who has explained a 404 for the hundredth time.

Installation

npm install http-eaas
# or
pnpm add http-eaas
# or
yarn add http-eaas

Quick Start

import { getExcuse } from 'http-eaas';

const message = getExcuse(404);
// "Yeah it's gone. Shocking, I know. Try not to spiral."

const another = getExcuse(404);
// "The page doesn't exist. Much like my will to explain why."

const serverError = getExcuse(500);
// "Something broke on our end. We're as surprised as you are. Almost."

API Reference

getExcuse(code: number): string

Returns a randomly selected excuse message for the given HTTP status code.

| Parameter | Type | Required | Description | | --------- | -------- | -------- | ---------------------------- | | code | number | Yes | A supported HTTP status code |

Returns: string — a sarcastic excuse message.

Throws: RangeError — if the code is not in the supported list. This includes floats, NaN, negative numbers, and unsupported codes.

try {
  const message = getExcuse(code);
  // use message
} catch (e) {
  if (e instanceof RangeError) {
    // code was not supported
  }
}

The error is specifically a RangeError, not a generic Error or TypeError.

Supported Status Codes

| Code | Name | | --------------------- | ------------------------------- | | 2xx Success | | | 200 | OK | | 201 | Created | | 202 | Accepted | | 204 | No Content | | 3xx Redirection | | | 301 | Moved Permanently | | 302 | Found | | 304 | Not Modified | | 307 | Temporary Redirect | | 308 | Permanent Redirect | | 4xx Client Errors | | | 400 | Bad Request | | 401 | Unauthorized | | 402 | Payment Required | | 403 | Forbidden | | 404 | Not Found | | 405 | Method Not Allowed | | 406 | Not Acceptable | | 408 | Request Timeout | | 409 | Conflict | | 410 | Gone | | 411 | Length Required | | 413 | Payload Too Large | | 415 | Unsupported Media Type | | 418 | I'm a Teapot ☕ | | 422 | Unprocessable Entity | | 423 | Locked | | 429 | Too Many Requests | | 451 | Unavailable For Legal Reasons | | 5xx Server Errors | | | 500 | Internal Server Error | | 501 | Not Implemented | | 502 | Bad Gateway | | 503 | Service Unavailable | | 504 | Gateway Timeout | | 505 | HTTP Version Not Supported | | 507 | Insufficient Storage | | 511 | Network Authentication Required |

Integration Examples

1. Generic try/catch wrapper (recommended)

import { getExcuse } from 'http-eaas';

function getUserFacingMessage(statusCode: number): string {
  try {
    return getExcuse(statusCode);
  } catch {
    return 'Something went wrong. We are on it. Probably.';
  }
}

2. Express.js global error handler

import { getExcuse } from 'http-eaas';
import type { Request, Response, NextFunction } from 'express';

app.use((err: any, req: Request, res: Response, next: NextFunction) => {
  const status = err.status || 500;
  let message: string;

  try {
    message = getExcuse(status);
  } catch {
    message = getExcuse(500);
  }

  res.status(status).json({ error: message });
});

3. Next.js custom error page

import { getExcuse } from 'http-eaas';
import type { NextPageContext } from 'next';

function ErrorPage({ statusCode }: { statusCode: number }) {
  let message: string;

  try {
    message = getExcuse(statusCode);
  } catch {
    message = 'Something went wrong.';
  }

  return (
    <div>
      <h1>{statusCode}</h1>
      <p>{message}</p>
    </div>
  );
}

ErrorPage.getInitialProps = ({ res, err }: NextPageContext) => {
  const statusCode = res?.statusCode ?? err?.statusCode ?? 404;
  return { statusCode };
};

export default ErrorPage;

Edge Cases

| Input | Result | | ------------------------- | ------------------- | | getExcuse(404) | Returns a string | | getExcuse(404.5) | Throws RangeError | | getExcuse(NaN) | Throws RangeError | | getExcuse(-1) | Throws RangeError | | getExcuse(999) | Throws RangeError | | getExcuse('404' as any) | Throws RangeError |

Always wrap getExcuse() in a try/catch in production.

How messages are selected

There are 20 messages per status code, selected uniformly at random on each call. The function is fully stateless — no deduplication, no seeding, no memory between calls. Call it twice with the same code and you may get the same message. That's fine. So is getting a different one.

Contributing

Contributions are welcome! Whether you want to improve existing messages or add support for a new status code — read the Contributing Guide to get started.

License

MIT