Error Handling Strategies

Error handling in the platform is built around one goal: making sure authentication errors reach the frontend so users can be prompted to grant access. Everything else is up to you.

When you call the gateway through fetchAsPrincipal() or fetchAsApp(), a non-2xx response is turned into an UpstreamHTTPError and thrown. You are free to catch, handle, log, or ignore these errors as your feature needs — there is no obligation to re-throw them.

The one case that matters is a 403 Forbidden (an API that needs user consent). These are recorded in a request-scoped error store the moment they happen, and the backend's error middleware forwards them to the frontend automatically — even if your code swallows the exception.