Better Auth · Pipe

onAPIError

onAPIError configures how Better Auth handles API failures. It can throw errors, invoke custom handling, redirect to an error URL, and customize the default error page.

How it works

onAPIError configures how Better Auth responds when an API request fails. You can make the failure throw, observe it with a handler, choose the error redirect URL, and customize the built-in error page.

Syntax

betterAuth({ onAPIError: { throw?: boolean, onError?: (error, ctx) => void, errorURL?: string, customizeDefaultErrorPage?: object } })

Parameters

Name	Type	Description
`onAPIError`	`object`	Controls API-error behavior, including throwing, custom handling, redirect destination, and default-page customization.
`throw`	`boolean`	Whether to throw when an API error occurs; documented default is `false`.
`onError`	`(error, ctx) => void`	Callback for custom error handling.
`errorURL`	`string`	URL used for error redirection; documented default is `/api/auth/error`.
`customizeDefaultErrorPage`	`object`	Settings for the default Better Auth error page.

Key points

onAPIError is the configuration section for controlling Better Auth API failures.
onError provides a callback for application-specific error handling.
customizeDefaultErrorPage lets you adjust Better Auth’s supplied error page.
The default error page can be inspected by starting the development server and opening its documented route.

Common mistakes

Enabling throw changes the default behavior: API errors are thrown instead of being handled without throwing.
If errorURL is omitted, Better Auth uses /api/auth/error, not the custom path shown in the example.

Example: Configure API error handling

import { betterAuth } from "better-auth";

export const auth = betterAuth({
  onAPIError: {
    throw: true,
    onError: (error, ctx) => {
      console.error("Auth error:", error);
    },
    errorURL: "/auth/error",
  },
});

Configures Better Auth to throw API errors, run custom handling, and use a custom error destination.

When to use it

Log authentication API failures

Centralized observability

Redirect users to a custom error page

Application-specific failure flow

Inspect or style the built-in error page

Local development

Interview questions

QWhat is onAPIError used for?

onAPIError is the Better Auth configuration object for API failures. Its documented options include throwing the error, invoking a custom handler, redirecting to an error URL, and customizing the default error page.

Follow-up: How would you preserve the built-in error page while adding logging? Leave errorURL and page customization unchanged, and use onError only for the logging side effect.

QHow do you configure API errors to throw?

Set throw: true to make an API error throw. The documented default is false, so throwing must be explicitly enabled.

Follow-up: What happens if throw is omitted? Better Auth uses the documented default of false, so the configuration does not request thrown API errors.

QHow can custom handling be added?

Use onError for custom error handling, such as logging the error and its context. The documented callback receives (error, ctx).

Follow-up: Which option controls the destination rather than callback behavior? errorURL specifies the URL used for redirecting on error.

API
APIError
Errors
customizeDefaultErrorPage

Source: Options. Checked 2026-10-15.