Errors

Authbound uses standard HTTP status codes. 2xx means success, 4xx means something in the request needs fixing, and 5xx means something went wrong on our side. Every error response has the same body:

{
  "object": "error",
  "code": "invalid_key_type",
  "message": "Invalid or missing API key"
}

Some errors add param (the field that failed) or details (structured data, such as the list of problems when a credential definition can’t be published). Branch on code. Messages are for people reading logs and can change without notice.

Handling errors in the SDK

@authbound/server throws AuthboundClientError for any non-2xx response. It carries the API’s code, the HTTP statusCode, and any details.

import { AuthboundClientError } from "@authbound/server";

try {
  await authbound.verifications.cancel(verificationId);
} catch (error) {
  if (error instanceof AuthboundClientError && error.code === "verification_terminal") {
    // Already finished. Nothing to cancel.
    return;
  }
  throw error;
}

Authentication

Status	`code`	What happened	Fix
401	`missing_key`	No `X-Authbound-Key` header, or it was empty.	Send your secret key in `X-Authbound-Key`.
401	`invalid_key_format`	The header value isn’t an Authbound key. Usually a client token sent in the wrong header.	Use a key starting with `sk_test_` or `sk_live_`.
401	`invalid_key_type`	You sent a publishable key (`pk_*`) where a secret key is required.	Use the secret key from the same project.
401	`invalid_key`	The key is well-formed but was revoked or doesn’t exist.	Create a new key in the dashboard.
403	`insufficient_scope`	The key is valid but lacks the scope this endpoint needs. The message names the scope.	Add the scope to the key in the dashboard, or use a different key.
401	`missing_token`	A status, events, or result request had no `Authorization: Bearer` client token.	Send the `clientToken` from the create response.
401	`invalid_token`	The client token is invalid or has expired. Tokens last as long as the verification, 15 minutes by default.	Create a new verification.
401	`missing_publishable_key`	A client-token request had no `X-Authbound-Publishable-Key`.	Send the publishable key alongside the client token.
403	`key_mismatch`	The publishable key belongs to a different project or environment than the verification.	Use the publishable key from the project that created the verification.
403	`origin_not_allowed`	The request’s `Origin` isn’t on the project’s allowed origins list.	Add your app’s origin under Allowed origins on the project page. Test mode always allows `localhost`.

Requests

Status	`code`	What happened	Fix
400	`validation_error`	The body or query failed validation. `message` describes the first problem; `param` names the field when available.	Check the field against the API reference.
400	`invalid_request`	The body isn’t valid JSON.	Send `Content-Type: application/json` with a JSON body.
400	`invalid_id`	An ID in the path is malformed.	Pass the ID exactly as returned by the API.
400	`invalid_cursor`	A pagination cursor is malformed.	Use the cursor from the previous page’s response unchanged.
404	`not_found`	The resource doesn’t exist in this project. Resources from other projects return the same error.	Check you’re using keys from the project that created it.
413	`payload_too_large`	The body is over the testbed’s 256 KiB limit.	Send a smaller body.
429	`rate_limited`	Too many requests.	Wait for the number of seconds in the `Retry-After` header, then retry.

Idempotency

Status	`code`	What happened	Fix
409	`idempotency_error`	A request with this `Idempotency-Key` is still being processed, or the key was reused with a different body.	Wait and retry with the same body, or use a new key for a different request.
503	`idempotency_unavailable`	Idempotency storage is temporarily unavailable, so the request wasn’t run.	Retry with the same key after a short delay.

Verifications

Status	`code`	What happened	Fix
400	`invalid_policy`	The `policy_id` isn’t a built-in preset or an active policy in this project.	See Policy not found.
409	`verification_start_in_progress`	The wallet flow is still starting.	Retry the same request after a moment.
409	`verification_terminal`	You tried to cancel a verification that has already finished.	Treat it as done. Read its final status instead.
400	`verification_not_terminal`	You asked for the result before the verification finished.	Wait for a terminal status or a webhook, then fetch the result.
503	`provider_not_configured`	The wallet provider for this policy isn’t set up for your project.	Contact Authbound support.
503	`realtime_unavailable`	The live events stream is temporarily unavailable.	Fall back to polling `/v1/verifications/{id}/status`. The SDKs do this automatically.

A verification that ends in failed is not an API error. The request succeeds, and the verification carries a failure_code. See failure codes.

Credential issuance

Status	`code`	What happened	Fix
404	`credential_definition_not_found`	The `credentialDefinitionId` or `vct` doesn’t match a published definition in this project.	Create the definition first.
409	`credential_definition_conflict`	A definition with this `credentialDefinitionId` already exists.	Load the existing one with `get`.
409	`credential_definition_not_publishable`	The draft isn’t ready to publish. `details.issues` lists what’s missing.	Fix each issue with `update`, then publish again.
409	`published_credential_definition_immutable`	You tried to change a published definition.	Create a new definition version instead.
409	`archived_credential_definition_immutable`	You tried to change an archived definition.	Create a new definition.
400	`unsupported_credential_format`	The definition’s `format` isn’t supported.	Use `dc+sd-jwt`.
400	`unsupported_credential_type`	The issuer can’t issue this credential type.	Check the definition’s `vct`.
502	`issuer_unavailable`	The credential issuer didn’t respond.	Retry with the same `Idempotency-Key`.

Server errors

Status	`code`	What happened	Fix
500	`internal_error`	Something went wrong on our side.	Retry with the same `Idempotency-Key`. If it keeps happening, contact support.
502	`backend_error`	An internal service didn’t respond correctly.	Retry with the same `Idempotency-Key`.

If you contact support at [email protected], include the full error body and the endpoint you called. Never include your secret key.

Overview

Generated endpoints

Handling errors in the SDK

Authentication

Requests

Idempotency

Verifications

Credential issuance

Server errors

​Handling errors in the SDK

​Authentication

​Requests

​Idempotency

​Verifications

​Credential issuance

​Server errors

Handling errors in the SDK

Authentication

Requests

Idempotency

Verifications

Credential issuance

Server errors