zuplo 6.67.32 → 6.68.0

package/docs/errors/gateway-timeout.mdx

@@ -0,0 +1,33 @@
+---
+title: Gateway Timeout (GATEWAY_TIMEOUT)
+---
+
+The upstream server did not respond within the allowed time.
+
+## Common Causes
+
+- **Slow upstream** — The backend server is taking too long to process the
+  request.
+- **Network issues** — Connectivity problems between Zuplo and the upstream
+  server.
+- **Large payloads** — The request or response body is very large and takes too
+  long to transfer.
+- **Upstream overload** — The backend server is under heavy load and unable to
+  respond in time.
+
+## How to Fix
+
+### For API Consumers
+
+- Retry the request after a short delay.
+- Check if the upstream service is experiencing known issues.
+- Reduce the request payload size if possible.
+
+### For API Operators
+
+- Verify the upstream server is healthy and responding.
+- Check the URL Forward or URL Rewrite handler configuration to ensure the
+  upstream URL is correct.
+- Review upstream server logs for errors or slow queries.
+- Consider increasing the timeout configuration if the upstream legitimately
+  needs more time to respond.

package/docs/errors/get-head-body-error.mdx

@@ -0,0 +1,41 @@
+---
+title: GET/HEAD Body Error (GET_HEAD_BODY_ERROR)
+---
+
+A GET or HEAD request included a body, which is not allowed. The
+[Fetch specification](https://fetch.spec.whatwg.org/) defines that GET and HEAD
+requests must not have a request body.
+
+## Why this happens
+
+The HTTP specification states that GET and HEAD requests are intended for
+retrieving resources and should not include a request body. While some HTTP
+clients allow sending a body with GET requests, the Zuplo runtime enforces the
+specification and rejects these requests.
+
+## How to fix
+
+- **Use a different HTTP method** - If the request needs to send data in the
+  body, use `POST`, `PUT`, or `PATCH` instead of `GET` or `HEAD`.
+- **Move data to query parameters** - If the request must remain a `GET`,
+  convert the body data to URL query parameters.
+- **Remove the body** - If the body was included unintentionally, remove it from
+  the request.
+
+## Common causes
+
+- **HTTP client defaults** - Some HTTP client libraries or frameworks
+  automatically attach a body to requests, even for GET methods. Check the
+  client configuration.
+- **Copied request configuration** - A request configuration copied from a POST
+  endpoint may still include a body when adapted for a GET endpoint.
+- **Framework behavior** - Certain frontend frameworks or API testing tools may
+  silently include an empty body or content-type header on GET requests.
+
+:::note
+
+This is a client-side issue. Update the request on the calling side to remove
+the body or change the HTTP method. No changes are needed on the Zuplo gateway
+configuration.
+
+:::

package/docs/errors/main-mod-error.mdx

@@ -0,0 +1,40 @@
+---
+title: Zuplo Main Module Error (MAIN_MOD_ERROR)
+---
+
+There was an error loading your Zuplo project. This error occurs at runtime when
+the project builds successfully but fails to initialize.
+
+## Common causes
+
+- **Runtime extension errors** - Code in a runtime extension throws an error
+  during initialization. This includes errors in the `runtimeInit` or other
+  lifecycle hooks.
+- **Invalid module exports** - A module does not export the expected functions
+  or objects that the Zuplo runtime requires.
+- **Unhandled exceptions at startup** - Top-level code in a module throws an
+  exception when the module is first loaded.
+- **Missing environment variables** - Code references an environment variable
+  that is not set, causing a failure during module initialization.
+
+## How to debug
+
+1. Check the runtime logs in the Zuplo portal for detailed error messages and
+   stack traces.
+2. Review any runtime extensions for errors in initialization code.
+3. Verify that all environment variables referenced in the code are configured
+   in the current environment.
+4. Test the project locally to reproduce the error with full debug output.
+
+:::warning
+
+This error prevents the entire project from loading. All routes return this
+error until the underlying issue is resolved and the project is redeployed.
+
+:::
+
+## Related resources
+
+- [Runtime Extensions](../programmable-api/runtime-extensions.mdx)
+- [Environment Variables](../articles/environment-variables.mdx)
+- [Logging](../articles/logging.mdx)

package/docs/errors/no-project-set.mdx

@@ -0,0 +1,41 @@
+---
+title: No Project Set Error (NO_PROJECT_SET)
+---
+
+This is a local development error that occurs when the Zuplo development server
+cannot load or find a valid project.
+
+## Common causes
+
+- **Build failure** - The project fails to build, preventing the local
+  development server from loading it. Check the terminal output for build
+  errors.
+- **Invalid project structure** - The project is missing required files such as
+  `routes.oas.json` or `package.json`.
+- **Wrong working directory** - The development server is started from a
+  directory that does not contain a Zuplo project.
+- **Corrupted dependencies** - The `node_modules` directory is missing or
+  contains corrupted packages.
+
+## Steps to fix
+
+1. Verify the terminal output for build errors and fix any reported issues.
+2. Confirm the project directory contains the required Zuplo project files
+   (`routes.oas.json`, `package.json`, and a `modules` directory).
+3. Ensure the development server starts from the root of the Zuplo project
+   directory.
+4. Delete the `node_modules` directory and run `pnpm install` to reinstall
+   dependencies.
+5. Restart the local development server after making changes.
+
+:::tip
+
+For additional troubleshooting help with local development, see
+[Local Development Troubleshooting](../articles/local-development-troubleshooting.mdx).
+
+:::
+
+## Related resources
+
+- [Local Development](../articles/local-development.mdx)
+- [Local Development Troubleshooting](../articles/local-development-troubleshooting.mdx)

package/docs/errors/not-found.mdx

@@ -0,0 +1,43 @@
+---
+title: Not Found Error (NOT_FOUND)
+---
+
+No route matched this request. The gateway could not find a configured route
+that matches the request path and HTTP method.
+
+## Common causes
+
+- **Incorrect request path** - The URL path does not match any route defined in
+  the routes configuration. Check for typos, missing path segments, or incorrect
+  casing.
+- **Wrong HTTP method** - The route exists but is configured for a different
+  HTTP method. For example, sending a `POST` request to a route that only
+  accepts `GET`.
+- **Route not deployed** - The route configuration has not been deployed to the
+  current environment. Verify the latest deployment includes the expected route.
+- **Missing path parameters** - The URL is missing required path segments or
+  parameters that the route expects.
+
+## How to debug
+
+1. Open the route designer in the Zuplo portal and verify the route exists with
+   the correct path and method.
+2. Check that the environment you are calling matches the environment where the
+   route is deployed.
+3. Verify the base URL is correct, including the project name and environment
+   subdomain.
+4. Review recent deployments to confirm the route configuration has been
+   published.
+
+:::tip
+
+Zuplo supports a custom not-found handler that allows you to customize the
+response when no route matches. See
+[Not Found Handler](../programmable-api/not-found-handler.mdx) for details.
+
+:::
+
+## Related resources
+
+- [Routes Designer](../articles/local-development-routes-designer.mdx)
+- [Deploying to the Edge](../articles/step-4-deploying-to-the-edge.mdx)

package/docs/errors/rate-limit-exceeded.mdx

@@ -0,0 +1,31 @@
+---
+title: Rate Limit Exceeded (RATE_LIMIT_EXCEEDED)
+---
+
+The request was rejected because the client exceeded the configured rate limit.
+
+## Common Causes
+
+- **Too many requests** — The client sent more requests than the rate limit
+  policy allows within the configured time window.
+- **Shared rate limit** — Multiple clients or API keys share a rate limit pool
+  that has been exhausted.
+- **Burst traffic** — A sudden spike in requests exceeded the allowed burst
+  capacity.
+
+## How to Fix
+
+- **Check the `Retry-After` header** — The response typically includes a
+  `Retry-After` header indicating how long to wait before sending another
+  request.
+- **Implement backoff** — Add exponential backoff and retry logic to the client.
+- **Request a higher limit** — If the current rate limit is too restrictive,
+  contact the API provider about upgrading the plan or adjusting limits.
+
+## For API Operators
+
+- Review the rate limiting policy configuration in the route settings.
+- Consider using
+  [dynamic rate limiting](../articles/step-5-dynamic-rate-limiting.mdx) to set
+  different limits per customer tier.
+- Check the rate limit metrics to determine if limits need adjustment.

package/docs/errors/schema-validation-failed.mdx

@@ -0,0 +1,51 @@
+---
+title: Schema Validation Failed (SCHEMA_VALIDATION_FAILED)
+---
+
+The incoming request body did not pass schema validation. The gateway validates
+the request body against a JSON Schema defined in the route configuration and
+rejects requests that do not conform.
+
+## How schema validation works
+
+When a route has a request body schema defined in the OpenAPI specification,
+Zuplo automatically validates incoming request bodies against that schema. If
+validation fails, the gateway returns a `400 Bad Request` response with details
+about which fields failed validation.
+
+## Common validation errors
+
+- **Missing required fields** - The request body is missing one or more fields
+  marked as `required` in the schema.
+- **Wrong data type** - A field value does not match the expected type (for
+  example, a string where a number is expected).
+- **Invalid enum value** - A field value is not one of the allowed values
+  defined in an `enum` constraint.
+- **Pattern mismatch** - A string field does not match the regular expression
+  defined in the `pattern` property.
+- **Out of range** - A numeric value falls outside the `minimum` or `maximum`
+  bounds defined in the schema.
+
+## How to fix
+
+1. Read the error response body carefully. It contains specific details about
+   which fields failed validation and why.
+2. Compare the request body against the JSON Schema defined in the route
+   configuration.
+3. Ensure all required fields are present and have the correct data types.
+4. Validate the request body locally using a JSON Schema validator before
+   sending the request.
+
+:::tip
+
+The validation error response includes the path to the invalid field and a
+description of the constraint that failed. Use this information to quickly
+identify and fix the issue.
+
+:::
+
+## How to configure schemas
+
+Define request body schemas in the `routes.oas.json` file using standard JSON
+Schema syntax within the OpenAPI `requestBody` definition. The schema specifies
+required fields, data types, formats, and constraints for the request body.

package/docs/errors/system-configuration-error.mdx

@@ -0,0 +1,44 @@
+---
+title: System Configuration Error (SYSTEM_CONFIGURATION_ERROR)
+---
+
+The runtime environment is not correctly configured. One or more required
+environment variables are missing or invalid.
+
+## Common causes
+
+- **Missing environment variables** - An environment variable referenced in the
+  project code or configuration is not set in the current environment.
+- **Wrong environment** - The request is hitting an environment (such as staging
+  or preview) where the required variables have not been configured.
+- **Deleted or renamed variables** - An environment variable was recently
+  deleted or renamed, but the code still references the old name.
+
+## How to check environment variables
+
+1. Open the Zuplo portal and navigate to the project settings.
+2. Review the environment variables for the target environment and verify all
+   required variables are present.
+3. Check the runtime logs for specific messages about which variable is missing.
+4. Compare the environment variables across environments to find discrepancies.
+
+:::note
+
+Environment variables are scoped to each environment. A variable set in
+production may not exist in staging or preview environments. Verify that all
+required variables are configured in every environment where the project is
+deployed.
+
+:::
+
+## How to fix
+
+1. Identify the missing variable from the error logs.
+2. Add the variable in the Zuplo portal under the project's environment variable
+   settings.
+3. Redeploy the project after adding the variable.
+
+## Related resources
+
+- [Environment Variables](../articles/environment-variables.mdx)
+- [Local Development Environment Variables](../articles/local-development-env-variables.mdx)

package/docs/errors/unauthorized.mdx

@@ -0,0 +1,50 @@
+---
+title: Unauthorized Error (UNAUTHORIZED)
+---
+
+The request failed authentication. The gateway could not verify the identity of
+the caller.
+
+## Common causes
+
+- **No `authorization` header** - The request does not include an
+  `authorization` header. Most authentication policies require this header to be
+  present.
+- **Invalid `authorization` header** - The header value is malformed or uses an
+  incorrect format. For bearer tokens, the expected format is
+  `Authorization: Bearer <token>`.
+- **Expired or revoked credentials** - The token or API key has expired, been
+  revoked, or is otherwise no longer valid.
+- **Wrong authentication scheme** - The request uses a different authentication
+  method than the one configured on the route (for example, sending a bearer
+  token when the route expects an API key).
+
+## How to test authentication
+
+1. Verify the token or API key is valid and has not expired.
+2. Confirm the `authorization` header format matches the expected scheme.
+3. Test with a known-good credential to rule out token-specific issues.
+4. Check the authentication policy configuration in the route designer to ensure
+   it matches the expected authentication method.
+
+:::note
+
+API key authentication in Zuplo uses the `Authorization: Bearer <api-key>`
+header format by default. See
+[API Key Authentication](../articles/api-key-authentication.mdx) for
+configuration details.
+
+:::
+
+## Common mistakes
+
+- Including extra whitespace or newline characters in the token value.
+- Sending the token as a query parameter instead of a header.
+- Using the wrong API key for the target environment (for example, a development
+  key against production).
+- Forgetting to add an authentication policy to the route.
+
+## Related resources
+
+- [API Key Authentication](../articles/api-key-authentication.mdx)
+- [API Key Administration](../articles/api-key-administration.mdx)

package/docs/errors/unknown-error.mdx

@@ -0,0 +1,42 @@
+---
+title: Unknown Error (UNKNOWN_ERROR)
+---
+
+This is an unhandled error in the Zuplo runtime. The error does not match any
+known error category.
+
+## Common scenarios
+
+- **Unhandled exception in custom code** - A request handler or policy throws an
+  unexpected error that is not caught by a try/catch block.
+- **Unexpected runtime behavior** - An edge case in the runtime produces an
+  error that is not categorized.
+- **Third-party service failures** - An external service call fails in an
+  unexpected way that is not handled by the code.
+
+## How to debug
+
+1. Check the runtime logs for the full error message and stack trace.
+2. Look for the specific request ID in the logs to find related log entries.
+3. Review recent code changes for potential unhandled error paths.
+4. Add try/catch blocks around external service calls and other error-prone code
+   to handle errors gracefully.
+
+## What to include when contacting support
+
+If the error persists and you cannot identify the cause, contact
+[Zuplo support](../articles/support.mdx) with the following information:
+
+- The **request ID** from the error response.
+- The **timestamp** of when the error occurred.
+- The **route path** and **HTTP method** of the failing request.
+- Any **recent changes** to the project code or configuration.
+- Relevant **log entries** from around the time of the error.
+
+:::tip
+
+Adding structured logging to request handlers makes it easier to diagnose
+unknown errors. See [Logging](../articles/logging.mdx) for details on
+configuring log output.
+
+:::

package/docs/errors.mdx

@@ -0,0 +1,14 @@
+# Zuplo Errors
+
+import { errors } from "../src/errors.ts";
+
+Zuplo provides detailed error messages to help diagnose and fix problems. Select
+an error below for causes and troubleshooting steps.
+
+<ul>
+  {errors.map(({ title, id }) => (
+    <li key={id}>
+      <a href={`./errors/${id}`}>{title}</a>
+    </li>
+  ))}
+</ul>