Error Handling

ProblemResponseFormatter

The ProblemResponseFormatter class provides a way to customize the format of problem responses in your API. This allows you to maintain consistent error response formats across your API while adhering to the RFC 7807 Problem Details specification.

Overview

The ProblemResponseFormatter class works in conjunction with the HttpProblems helper to format error responses. It can be used to customize how problem details are serialized and presented to API consumers.

Static Methods

format

Formats a problem response with the provided details.

static format(
  problemDetails: ProblemResponseDetails,
  request: ZuploRequest,
  context: ZuploContext
): Promise<Response>
typescript

Parameters

problemDetails: ProblemResponseDetails - The problem details to format
request: ZuploRequest - The current request object
context: ZuploContext - The current context object

Returns

A Promise<Response> containing the formatted problem response.

Usage

Basic Usage

import {
  ProblemResponseFormatter,
  ZuploRequest,
  ZuploContext,
} from "@zuplo/runtime";

export default async function handler(
  request: ZuploRequest,
  context: ZuploContext,
) {
  try {
    // Your handler logic
  } catch (error) {
    const problemDetails = {
      type: "https://example.com/errors/validation-failed",
      title: "Validation Failed",
      status: 400,
      detail: "The request body contains invalid fields",
      instance: request.url,
    };

    return ProblemResponseFormatter.format(problemDetails, request, context);
  }
}
typescript

Custom Error Handler

import {
  ProblemResponseFormatter,
  RuntimeExtensions,
  ProblemResponseDetails,
} from "@zuplo/runtime";

export function runtimeInit(runtime: RuntimeExtensions) {
  runtime.addErrorHandler(async (error, request, context) => {
    // Map errors to problem details
    const problemDetails: ProblemResponseDetails = {
      type: "https://api.example.com/errors/internal",
      title: "Internal Server Error",
      status: 500,
      detail: error.message,
      instance: request.url,
      // Add custom extensions
      extensions: {
        errorId: crypto.randomUUID(),
        timestamp: new Date().toISOString(),
      },
    };

    return ProblemResponseFormatter.format(problemDetails, request, context);
  });
}
typescript

Problem Response Details Interface

The ProblemResponseDetails interface defines the structure of problem details:

interface ProblemResponseDetails {
  type?: string; // URI reference for the problem type
  title: string; // Short, human-readable summary
  status: number; // HTTP status code
  detail?: string; // Human-readable explanation
  instance?: string; // URI reference for the specific occurrence
  extensions?: Record<string, any>; // Additional problem-specific details
}
typescript

Integration with HttpProblems

The ProblemResponseFormatter is used internally by the HttpProblems helper class. When you use HttpProblems methods, they utilize ProblemResponseFormatter to ensure consistent formatting:

// This internally uses ProblemResponseFormatter
return HttpProblems.badRequest(request, context, {
  detail: "Invalid request parameters",
});
typescript

Custom Formatting Example

You can extend problem responses with custom fields:

import { ProblemResponseFormatter } from "@zuplo/runtime";

export async function customErrorHandler(
  error: Error,
  request: ZuploRequest,
  context: ZuploContext,
) {
  const problemDetails = {
    type: "https://api.example.com/errors/business-rule",
    title: "Business Rule Violation",
    status: 422,
    detail: error.message,
    instance: request.url,
    // Custom extensions
    extensions: {
      code: "BRV_001",
      timestamp: new Date().toISOString(),
      requestId: context.requestId,
      supportUrl: "https://support.example.com",
    },
  };

  return ProblemResponseFormatter.format(problemDetails, request, context);
}
typescript

Response Format

The formatter produces responses in the standard Problem Details format:

{
  "type": "https://api.example.com/errors/validation-failed",
  "title": "Validation Failed",
  "status": 400,
  "detail": "The 'email' field is invalid",
  "instance": "/api/users",
  "code": "VAL_001",
  "timestamp": "2024-01-15T10:30:00Z",
  "requestId": "req_123abc"
}
json