Error handling

Yggdrasil Server has a built-in error handling mechanism. To use it, simply throw a YggdrasilStatus object from inside a request handler:

throw new YggdrasilStatus(404, "INVALID_ROUTE", "The page you're trying to load doesn't exist.");

For your convenience, Yggdrasil Server also provides an assert function that throws a YggdrasilStatus for you upon failure:

ygg.assert(user.isAuthenticated, 401, "AUTH_REQUIRED", "You need to be signed in to load this page.");

YggdrasilStatus parameters

The YggdrasilStatus constructor and ygg.assert function share a common set of parameters. Those parameters are:

1. The HTTP status code to return. The name of the status code should match the nature of the error.
2. A custom status code (something like "AUTH_REQUIRED"). This should be a brief error ID that should allow you to identify where the error was thrown from in your code, and also allow users to identify the error through bug reports, web searches, etc.
3. (optional) A custom status message to show to the user to help them understand the nature of the error, how they might resolve it, additional details, etc.

Built-in errors

Yggdrasil Server itself may throw a YggdrasilStatus if your configuration causes an unworkable state. When Yggdrasil Server itself throws an error, it will use an status code prefixed with YGG_. Please don't prefix any of your own status codes with YGG_.

Just because one of these errors is thrown doesn't mean your app is badly configured, however. For example, if your server's base URL is in a subdirectory, and it's deployed behind a reverse proxy that routes other directories elsewhere, you may receive a YGG_BASE_URL_MISMATCH when you try to load the root path directly (without going through the proxy), but this would be expected since your reverse proxy would otherwise route that path somewhere else on the user-facing URL.

List of built-in errors

HTTP status code	Yggdrasil status code	Description
404	YGG_BASE_URL_MISMATCH	Thrown when your base URL indicates that your server is deployed in a sub-directory (e.g. /app), but the requested URL does not use that prefix.
404	YGG_ROUTE_NOT_FOUND	Thrown when YggdrasilRouter can't find a route that matches the request's path.
405	YGG_ROUTE_METHOD_MISMATCH	Thrown when YggdrasilRouter finds route(s) that matches the request's path, but none of them match the request's method.
404	YGG_API_NOT_FOUND	Thrown when YggdrasilConduitServer can't find a Conduit API implementation that matches the request.
400	YGG_BAD_API_REQUEST	Thrown when YggdrasilConduitServer detects an invalid Conduit API request.
500	YGG_BADLY_CONFIGURED	Thrown when Yggdrasil Server is unable to proceed due to a misconfiguration, such as missing a required option, contradictory settings, etc. The error message describes the nature of the misconfiguration.

Status pages

When a YggdrasilStatus object is thrown and uncaught by your handler, Yggdrasil Server will return a Response with the corresponding HTTP status code and a generated status page:

Request Accept	Response type	Description
application/json+jottocraft-ygg-res	application/json+jottocraft-ygg-res	Returns all the information necessary to pass along the status to the callee's instance of Yggdrasil Server. Please see the Conduit feature documentation for more information.
application/json	application/json	This currently does the same thing as requests accepting application/json+jottocraft-ygg-res.
text/html	text/html	Calls ygg.options.generateHtmlStatusPage() if this is something you've implemented.
Anything else	text/plain	Returns a presentable plaintext status page detailing the error.

Uncaught errors

The bulk of this document details how Yggdrasil Server handles uncaught YggdrasilStatus objects to generate a status page. Please keep in mind that this behavior only applies to YggdrasilStatus objects. Any other errors that happen in your code will remain uncaught, and it's up to you to determine how those should be handled.