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:
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.
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:
| Situation | Diagnostic |
|---|---|
| Malformed secret key at construct time | Prefix must be sk_test_ or sk_live_ (INVALID_API_KEY_FORMAT) |
Policy create with legacy returnAttrs | returnAttrs is no longer accepted... |
| Policy create with zero or multiple targets | Exactly one of attestationType, credentialDefinitionId, or vct |
| Attestation policy missing ecosystem/format | Built-in attestation policies require both |
| Custom policy with non–SD-JWT format | Custom credential policies only support dc+sd-jwt |
Invalid requestedClaims | Empty list, duplicates after alias resolution, invalid value types, or eligibility claims other than [true] |
VALIDATION_ERROR includes details, it is a Zod-style structure for fixing the request. See Create your own policy and Troubleshooting — policy create.
Authentication
Athttps://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.
| 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. |
| 400 | unsupported_contract_revision | The 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. |
| 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 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. |
| 429 | rate_limited | Too many requests. | Wait for the number of seconds in the Retry-After header, then retry. |
validation_error and param: "body" instead of payload_too_large. The limit is documented on POST /v1/verifications.
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 | credential_type_retired | The policy names a credential type that Authbound (or its owner) no longer verifies. | Move the policy to a credential type that is still offered. |
| 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. |
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. |