Error Codes

Most SDK failures are a plain Error whose message says what went wrong. A handful carry a machine-readable code you can branch on. This page lists both: the codes first, then the messages you are most likely to see.

How errors surface

import BuildBase from '@buildbase/sdk';

const bb = new BuildBase({
  serverUrl: process.env.BUILDBASE_SERVER_URL!,
  orgId: process.env.BUILDBASE_ORG_ID!,
  onError: (error, { method, path }) => {
    console.error(`[buildbase] ${method} ${path}`, error.message);
  },
});

Aborted requests (an AbortError, from your own AbortController or an unmounted component) are treated as cancellations: the SDK does not report them, and you can ignore them too.

Error codes

Credits

import {
  useConsumeCredits,
  useSaaSAuth,
  useSaaSWorkspaces,
} from '@buildbase/sdk/react';

function Generate() {
  const { currentWorkspace } = useSaaSWorkspaces();
  const { consumeCredits } = useConsumeCredits(currentWorkspace?._id);
  const { openCreditStore } = useSaaSAuth();

  async function run() {
    try {
      await consumeCredits({ amount: 10, description: 'AI generation' });
    } catch (err: any) {
      if (err.code === 'INSUFFICIENT_CREDITS') {
        alert(
          `You have ${err.available} credits, this needs ${err.requested}.`
        );
        openCreditStore();
        return;
      }
      throw err;
    }
  }

  return <button onClick={run}>Generate</button>;
}

Account and security

The calls behind the Profile and Security screens (WorkspaceApi) keep the server's sentence as the message and carry its reason as err.code. Two of them can come from any change the user makes:

Neither signs the user out. The rest are listed with their feature: Two-step sign-in, Phone sign-in, Connected Accounts, Usernames, Guest users and Deleting accounts.

Uploads and storage

An upload through the SDK (useUpload, UploadsApi) rejects with an Error that has err.status and err.code set. uploadFailureOf(err) turns them into a reason you can word yourself - tooLarge, invalid, disabled, userLimit, unavailable or failed - which useUpload also returns as failure. The same codes come back from the console API's asset uploads and from a form's file field, where your own code reads the response body.

An end user and a form visitor never see PLAN_LIMIT_REACHED: the organization's plan is not theirs to act on, so they get UPLOADS_UNAVAILABLE with 503.

Agent token verification

These are the code values on AppBridgeError, thrown by verifyClientJwt(), verifyAppTokenRequest() and verifyAppRevokeRequest() when a request from BuildBase to your applicationTokenUrl or applicationRevokeUrl fails verification.

handleAppTokenRequest() and handleAppRevokeRequest() catch these for you and return a 401 whose body message is the code, so you only handle AppBridgeError directly when you call the verify functions yourself.

Tracking codes

The code on an sdk_error tracking event is SDK_ERROR when an operation threw an Error, and UNKNOWN_ERROR when it threw something that was not an Error. Use component and action on the same event to find which operation failed.

Common error messages

These have no code; match on the situation rather than the exact string.

Messages from the server

When the API responds with an error, the thrown message is the server's own message when it sends one. When it does not, the SDK falls back to <action> (<status>: <reason>), for example Failed to fetch credit balance (403: Forbidden - You do not have permission):

Some methods also attach the HTTP status as err.status. It is not set on every call, so check for it before relying on it.

Next steps

• Troubleshooting - symptoms and fixes by area.
• Server SDK - the BuildBase client and its config options.