ZuploZuplo
LoginSign Up
  • Documentation
  • API Reference
Introduction
Getting Started
    Develop using the Portal
      1 - Setup Your Gateway2 - Rate Limiting3 - API Key Auth4 - Deploy5 - Dynamic Rate LimitingMCP - Quick start
    Develop Locally
      1 - Setup Your Gateway2 - Rate Limiting3 - API Key Auth
Concepts
Development
Policies
Handlers
API Keys
MCP Server
MCP Gateway
AI Gateway
Developer Portal
Monetization
Deploying & Source Control
Observability
Networking & Infrastructure
Account Management
Programming API
    Overview
    Request & Context
    Configuration
    Caching APIs
    Data Management
    Extensions & Hooks
    Error Handling
      Runtime ErrorsCustom Not Found HandlerProblem Details HelperProblemResponseFormatter
    Logging & Observability
    Types and Interfaces
    Web Standards
    Advanced Topics
Build with AI
Zuplo CLI
Migration Guides
Platform LimitsSecuritySupportTrust & ComplianceChangelog
powered by Zudoku
Error Handling

Custom Not Found Handler

By default, Zuplo will return a 404 (using problem details) if no matching path/method combination is found. You can override this behavior by adding code to the zuplo.runtime.ts file (see runtime extensions).

For example - a custom not found handler can be used to return a 405 - Method Not Allowed if a matching path is found, but no matching METHOD, here is an example function that would implement this behavior:

Code
import { HttpProblems, RuntimeExtensions } from "@zuplo/runtime"; export function runtimeInit(runtime: RuntimeExtensions) { //add a custom not found handler runtime.notFoundHandler = async (request, context, notFoundOptions) => { if (notFoundOptions.routesMatchedByPathOnly.length > 0) { // It's required to have an 'Allow' header with a 405 response // Generate a string of allowed methods const allowedMethods = notFoundOptions.routesMatchedByPathOnly .map((route) => route.methods) .reduce((acc, val) => acc.concat(val), []) .join(", "); return HttpProblems.methodNotAllowed( request, context, {}, { allow: allowedMethods }, ); } return HttpProblems.notFound(request, context); }; }

An error in your zuplo.runtime.ts can break your gateway for all requests. Be sure to carefully review any custom code in this file and add generous error handling where appropriate.

Edit this page
Last modified on March 23, 2026
Runtime ErrorsProblem Details Helper
TypeScript