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;
}

Client-side validation (no HTTP request)

@authbound/server validates some inputs locally before calling the API. Invalid policy options throw AuthboundClientError with code VALIDATION_ERROR (uppercase). Malformed API keys use INVALID_API_KEY_FORMAT. They are not API responses and do not use the REST validation_error code. Common cases:
SituationDiagnostic
Malformed secret key at construct timePrefix must be sk_test_ or sk_live_ (INVALID_API_KEY_FORMAT)
Policy create with legacy returnAttrsreturnAttrs is no longer accepted...
Policy create with zero or multiple targetsExactly one of attestationType, credentialDefinitionId, or vct
Attestation policy missing ecosystem/formatBuilt-in attestation policies require both
Custom policy with non–SD-JWT formatCustom credential policies only support dc+sd-jwt
Invalid requestedClaimsEmpty list, duplicates after alias resolution, invalid value types, or eligibility claims other than [true]
When VALIDATION_ERROR includes details, it is a Zod-style structure for fixing the request. See Create your own policy and Troubleshooting — policy create.

Authentication

At https://sandbox.authbound.io and your live API URL, every secret key problem returns 401 with code invalid_api_key: a missing header, a publishable key or client token in its place, and a key that was revoked or never existed. The missing_key, invalid_key_format, invalid_key_type and invalid_key codes below come from https://api.authbound.io, the SDK default when the API URL isn’t set. See Troubleshooting.
StatuscodeWhat happenedFix
401missing_keyNo X-Authbound-Key header, or it was empty.Send your secret key in X-Authbound-Key.
401invalid_key_formatThe 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_.
401invalid_key_typeYou sent a publishable key (pk_*) where a secret key is required.Use the secret key from the same project.
401invalid_keyThe key is well-formed but was revoked or doesn’t exist.Create a new key in the dashboard.
403insufficient_scopeThe 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.
401missing_tokenA status, events, or result request had no Authorization: Bearer client token.Send the clientToken from the create response.
401invalid_tokenThe client token is invalid or has expired. Tokens last as long as the verification, 15 minutes by default.Create a new verification.
401missing_publishable_keyA client-token request had no X-Authbound-Publishable-Key.Send the publishable key alongside the client token.
403key_mismatchThe publishable key belongs to a different project or environment than the verification.Use the publishable key from the project that created the verification.
403origin_not_allowedThe 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

StatuscodeWhat happenedFix
400validation_errorThe body or query failed validation. message describes the first problem; param names the field when available.Check the field against the API reference.
400invalid_requestThe body isn’t valid JSON.Send Content-Type: application/json with a JSON body.
400invalid_idAn ID in the path is malformed.Pass the ID exactly as returned by the API.
400invalid_cursorA pagination cursor is malformed.Use the cursor from the previous page’s response unchanged.
400unsupported_contract_revisionThe Authbound-Contract-Revision header isn’t exactly one supported revision. Empty, repeated, comma-joined, upper-case and retired values are all rejected. message lists the supported revisions and param is Authbound-Contract-Revision.Send one supported revision, or omit the header to get the latest. See Contract revisions.
404not_foundThe 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.
413payload_too_largeThe raw creation body exceeds the enabled isolated testbed limit (256 KiB / 262144 bytes). Applies to verification and issuance create routes, including keyed requests.Shrink large optional fields such as metadata. See Request body too large.
429rate_limitedToo many requests.Wait for the number of seconds in the Retry-After header, then retry.
Customer-controlled edge deployments cap verification creation bodies at 64 KiB (65536 bytes) after validating the secret-key header. Those rejections return 413 with validation_error and param: "body" instead of payload_too_large. The limit is documented on POST /v1/verifications.

Idempotency

StatuscodeWhat happenedFix
409idempotency_errorA 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.
503idempotency_unavailableIdempotency storage is temporarily unavailable, so the request wasn’t run.Retry with the same key after a short delay.

Verifications

StatuscodeWhat happenedFix
400invalid_policyThe policy_id isn’t a built-in preset or an active policy in this project.See Policy not found.
409verification_start_in_progressThe wallet flow is still starting.Retry the same request after a moment.
409credential_type_retiredThe policy names a credential type that Authbound (or its owner) no longer verifies.Move the policy to a credential type that is still offered.
409verification_terminalYou tried to cancel a verification that has already finished.Treat it as done. Read its final status instead.
400verification_not_terminalYou asked for the result before the verification finished.Wait for a terminal status or a webhook, then fetch the result.
503provider_not_configuredThe wallet provider for this policy isn’t set up for your project.Contact Authbound support.
503realtime_unavailableThe 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

StatuscodeWhat happenedFix
404credential_definition_not_foundThe credentialDefinitionId or vct doesn’t match a published definition in this project.Create the definition first.
409credential_definition_conflictA definition with this credentialDefinitionId already exists.Load the existing one with get.
409credential_definition_not_publishableThe draft isn’t ready to publish. details.issues lists what’s missing.Fix each issue with update, then publish again.
409published_credential_definition_immutableYou tried to change a published definition.Create a new definition version instead.
409archived_credential_definition_immutableYou tried to change an archived definition.Create a new definition.
400unsupported_credential_formatThe definition’s format isn’t supported.Use dc+sd-jwt.
400unsupported_credential_typeThe issuer can’t issue this credential type.Check the definition’s vct.
502issuer_unavailableThe credential issuer didn’t respond.Retry with the same Idempotency-Key.

Server errors

StatuscodeWhat happenedFix
500internal_errorSomething went wrong on our side.Retry with the same Idempotency-Key. If it keeps happening, contact support.
502backend_errorAn 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.