Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

5.1 KB
Raw Blame
import type { FastifyInstance } from "fastify";

interface StructuredApiError extends Record<string, unknown> {
  code: string;
  error: string;
  message: string;
  resolution: string;
}

const defaultsByStatus: Record<number, { code: string; message: string; resolution: string }> = {
  400: {
    code: "INVALID_REQUEST",
    message: "The request is invalid.",
    resolution: "Check the request parameters and body against https://rybbit.com/openapi.json.",
  },
  401: {
    code: "AUTHENTICATION_REQUIRED",
    message: "Authentication is required.",
    resolution: "Send a valid API key in the Authorization header as a Bearer token.",
  },
  403: {
    code: "FORBIDDEN",
    message: "The credential does not have permission for this operation.",
    resolution: "Use a credential with the required scope and Site or Organization access.",
  },
  404: {
    code: "NOT_FOUND",
    message: "The requested API resource was not found.",
    resolution: "Check identifiers and paths against https://rybbit.com/openapi.json.",
  },
  405: {
    code: "METHOD_NOT_ALLOWED",
    message: "The HTTP method is not supported for this path.",
    resolution: "Choose a method listed for this path in https://rybbit.com/openapi.json.",
  },
  409: {
    code: "CONFLICT",
    message: "The request conflicts with the current resource state.",
    resolution: "Refresh the resource, resolve the conflicting state, and retry.",
  },
  413: {
    code: "PAYLOAD_TOO_LARGE",
    message: "The request body is too large.",
    resolution: "Reduce the payload size or split it into smaller requests.",
  },
  415: {
    code: "UNSUPPORTED_MEDIA_TYPE",
    message: "The request media type is not supported.",
    resolution: "Send JSON with Content-Type: application/json unless the operation documents another type.",
  },
  429: {
    code: "RATE_LIMITED",
    message: "Rate limit exceeded.",
    resolution: "Wait for the advertised retry period, then retry the request.",
  },
  500: {
    code: "INTERNAL_ERROR",
    message: "The server could not complete the request.",
    resolution: "Retry with exponential backoff. Contact support if the error persists.",
  },
};

function defaultsFor(statusCode: number) {
  return defaultsByStatus[statusCode] ?? (statusCode >= 500 ? defaultsByStatus[500] : defaultsByStatus[400]);
}

function isRecord(value: unknown): value is Record<string, unknown> {
  return typeof value === "object" && value !== null && !Array.isArray(value);
}

export function normalizeApiError(statusCode: number, payload: unknown): StructuredApiError {
  const existing = isRecord(payload)
    ? payload
    : typeof payload === "string"
      ? { error: payload }
      : Array.isArray(payload)
        ? { details: payload }
        : {};
  const defaults = defaultsFor(statusCode);
  const message =
    typeof existing.message === "string"
      ? existing.message
      : typeof existing.error === "string"
        ? existing.error
        : defaults.message;

  return {
    ...existing,
    error: typeof existing.error === "string" ? existing.error : message,
    code: typeof existing.code === "string" ? existing.code : defaults.code,
    message,
    resolution: typeof existing.resolution === "string" ? existing.resolution : defaults.resolution,
  };
}

function pathname(url: string): string {
  return url.split("?", 1)[0];
}

function isApiPath(path: string): boolean {
  return path === "/api" || path.startsWith("/api/");
}

function isMcpPath(path: string): boolean {
  return path === "/api/mcp" || path.startsWith("/api/mcp/");
}

function serializedPayloadValue(payload: unknown): unknown {
  const text = Buffer.isBuffer(payload) ? payload.toString("utf8") : typeof payload === "string" ? payload : undefined;
  if (text === undefined) return payload;

  try {
    return JSON.parse(text);
  } catch {
    return text;
  }
}

export function registerApiErrorResponses(server: FastifyInstance): void {
  server.addHook("onSend", async (request, reply, payload) => {
    const path = pathname(request.url);
    if (reply.statusCode < 400 || !isApiPath(path) || isMcpPath(path)) return payload;

    const normalized = normalizeApiError(reply.statusCode, serializedPayloadValue(payload));
    reply.type("application/json; charset=utf-8");
    reply.header("Cache-Control", "no-store");
    reply.header("X-Content-Type-Options", "nosniff");
    reply.removeHeader("Content-Length");
    return JSON.stringify(normalized);
  });

  server.setNotFoundHandler(async (request, reply) => {
    const path = pathname(request.url);
    if (isApiPath(path)) {
      return reply.status(404).send({
        error: `No API route matches ${request.method} ${path}.`,
        code: "API_ROUTE_NOT_FOUND",
        message: `No API route matches ${request.method} ${path}.`,
        resolution: "Read https://rybbit.com/openapi.json and choose a documented operation.",
        details: { method: request.method, path },
      });
    }

    return reply.status(404).send({
      error: "Resource not found.",
      code: "NOT_FOUND",
      message: "Resource not found.",
      resolution: "Check the requested path and try again.",
    });
  });
}