> ## Documentation Index
> Fetch the complete documentation index at: https://neverminedag-feat-use-cases-section.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.
# API error codes
> Catalogue of every BCK.* error code returned by the Nevermined API
Every error response from the Nevermined API carries a stable `code` (e.g. `BCK.X402.0008`). The table below enumerates every code, its HTTP status, category, canonical message, and remediation hint. Pages on this site are anchored by code — link directly to `#bck-x402-0008` from your error handlers, runbooks, or support tickets.
Locked response fields are `code`, `message`, and the HTTP status. Optional fields (`hint`, `docsUrl`, `category`, `retryable`, `correlationId`) appear only when supplied. Consumers that branch only on `code` and `message` ignore the rest transparently.
## Namespaces
* [`BCK.AGENT`](#bck-agent) — 11 codes
* [`BCK.APIKEY`](#bck-apikey) — 12 codes
* [`BCK.AUTH`](#bck-auth) — 9 codes
* [`BCK.BRAINTREE`](#bck-braintree) — 9 codes
* [`BCK.COMMON`](#bck-common) — 29 codes
* [`BCK.CREDITS`](#bck-credits) — 6 codes
* [`BCK.DELEGATION`](#bck-delegation) — 2 codes
* [`BCK.GUEST`](#bck-guest) — 2 codes
* [`BCK.LEGAL_DOCS`](#bck-legal_docs) — 6 codes
* [`BCK.METRIC`](#bck-metric) — 5 codes
* [`BCK.NOTIF`](#bck-notif) — 9 codes
* [`BCK.OAUTH`](#bck-oauth) — 6 codes
* [`BCK.OBSERVABILITY`](#bck-observability) — 5 codes
* [`BCK.ORGANIZATIONS`](#bck-organizations) — 15 codes
* [`BCK.PAYPAL`](#bck-paypal) — 1 code
* [`BCK.PLANS`](#bck-plans) — 1 code
* [`BCK.POINT`](#bck-point) — 19 codes
* [`BCK.PROTOCOL`](#bck-protocol) — 47 codes
* [`BCK.STRIPE`](#bck-stripe) — 32 codes
* [`BCK.STRIPE.CONNECT`](#bck-stripe-connect) — 5 codes
* [`BCK.TRANSCODING`](#bck-transcoding) — 1 code
* [`BCK.TXS`](#bck-txs) — 10 codes
* [`BCK.USER_PROFILE`](#bck-user_profile) — 2 codes
* [`BCK.VISA`](#bck-visa) — 18 codes
* [`BCK.WIDGET`](#bck-widget) — 5 codes
* [`BCK.WIDGET_KEYS`](#bck-widget_keys) — 2 codes
* [`BCK.WIDGET_SESSION`](#bck-widget_session) — 12 codes
* [`BCK.X402`](#bck-x402) — 17 codes
`BCK.AGENT`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------- | ---- | -------- | --------- | ---------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.AGENT.0001` | 400 | business | — | Invalid Agent Execution Status | |
| `BCK.AGENT.0002` | 500 | business | — | Error updating step agent | |
| `BCK.AGENT.0003` | 403 | business | — | Unable to create task for agent | |
| `BCK.AGENT.0004` | 403 | business | — | Invalid user | |
| `BCK.AGENT.0005` | 403 | business | — | Unable to get task for did, task and user | |
| `BCK.AGENT.0006` | 403 | business | — | Unable to find tasks by subscriber | |
| `BCK.AGENT.0007` | 404 | business | — | Connection not found for clientId | |
| `BCK.AGENT.0008` | 500 | business | — | Error registering websocket connection | |
| `BCK.AGENT.0009` | 403 | business | — | Error creating steps for agent | |
| `BCK.AGENT.0010` | 403 | business | — | Task not found or completed | |
| `BCK.AGENT.0011` | 500 | internal | ❌ | Agent lookup failed: agent with the given entryId not found in service layer | The service-layer findOneById returned null. The original behaviour was a generic 500; consumer code that needs 404 semantics should use BCK.PROTOCOL.0004. |
`BCK.APIKEY`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------- | ---- | -------- | --------- | ----------------------------------------------------- | ---- |
| `BCK.APIKEY.0001` | 403 | auth | — | API Key not registered, you need to register it first | |
| `BCK.APIKEY.0002` | 404 | auth | — | API Key with given hash not found | |
| `BCK.APIKEY.0003` | 401 | auth | — | Unable to revoke API Key | |
| `BCK.APIKEY.0004` | 401 | auth | — | Invalid Nevermined API Key | |
| `BCK.APIKEY.0006` | 401 | auth | — | Invalid Nevermined Key Metadata | |
| `BCK.APIKEY.0007` | 401 | auth | — | API Key issuer does not match user address | |
| `BCK.APIKEY.0008` | 403 | auth | — | API Key with hash already exists | |
| `BCK.APIKEY.0009` | 500 | auth | — | Error search API Key trannsactions | |
| `BCK.APIKEY.0010` | 401 | auth | — | Expiration date must be in the future | |
| `BCK.APIKEY.0011` | 500 | auth | — | Error searching user API Keys | |
| `BCK.APIKEY.0012` | 401 | auth | — | Unable to generate assertion | |
| `BCK.APIKEY.0013` | 401 | auth | — | Malformed API Key payload | |
`BCK.AUTH`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------- | ---- | -------- | --------- | --------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.AUTH.0001` | 500 | auth | — | Error registering API Key | |
| `BCK.AUTH.0002` | 401 | auth | — | Authentication required: credentials are missing, expired or invalid | |
| `BCK.AUTH.0003` | 403 | auth | — | Forbidden: caller is not the owner of this resource and lacks an admin role | |
| `BCK.AUTH.0004` | 403 | auth | ❌ | Organisation admin privileges required | The caller is not an active admin of the target organisation. Prefer the more specific siblings (BCK.AUTH.0005-0009) at new throw sites; this code remains as a catch-all. |
| `BCK.AUTH.0005` | 403 | auth | ✅ | Unable to verify organisation membership | The membership lookup itself failed (e.g. transient DB error). Check the cause field on the server log; retry once. |
| `BCK.AUTH.0006` | 403 | auth | ❌ | Caller does not belong to any organisation | Add the user as a member of the target organisation before calling admin-scoped endpoints. |
| `BCK.AUTH.0007` | 403 | auth | ❌ | Caller does not have administrator privileges | The caller is a member but not an admin. Promote the role via the organisation admin UI / API, or call from an admin account. |
| `BCK.AUTH.0008` | 403 | auth | ❌ | Caller account is not active | The user is suspended/disabled. Reactivate via the admin UI before retrying. |
| `BCK.AUTH.0009` | 403 | auth | ❌ | Target organisation is not active | The org has been deactivated (subscription lapsed, manual disable, etc.). Reactivate before performing admin operations. |
`BCK.BRAINTREE`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------------- | ---- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ---- |
| `BCK.BRAINTREE.0001` | 500 | integration | — | Braintree platform gateway is not configured | |
| `BCK.BRAINTREE.0002` | 400 | integration | — | Braintree charge failed | |
| `BCK.BRAINTREE.0003` | 502 | integration | — | Braintree OAuth token refresh failed | |
| `BCK.BRAINTREE.0004` | 400 | integration | — | Plan owner has not connected a Braintree merchant account | |
| `BCK.BRAINTREE.0005` | 400 | integration | — | Plan is not a fiat plan — cannot be purchased via Braintree | |
| `BCK.BRAINTREE.0006` | 409 | integration | — | Plan owner has no Braintree merchant account connected | |
| `BCK.BRAINTREE.0007` | 400 | integration | — | Plan owner's Braintree account does not have a merchant account in the plan's currency | |
| `BCK.BRAINTREE.0008` | 400 | integration | — | Cannot create a Braintree plan in this currency: your Braintree account has no merchant account in that currency. Add one in your Braintree dashboard, then disconnect and reconnect to refresh. | |
| `BCK.BRAINTREE.0009` | 400 | integration | — | Plan metadata is missing currency. Plans must specify a currency to be settled via Braintree. | |
`BCK.COMMON`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------- | ---- | ----------- | --------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.COMMON.0001` | 500 | internal | — | Unable to initialize Nevermined instance | |
| `BCK.COMMON.0002` | 500 | internal | — | Unable to generate session key | |
| `BCK.COMMON.0003` | 500 | internal | — | Unable to retrieve fees information from Nevermined | |
| `BCK.COMMON.0004` | 500 | internal | — | Unable to calculate Asset Price | |
| `BCK.COMMON.0005` | 500 | internal | — | Unable to load NFT Contract | |
| `BCK.COMMON.0006` | 500 | internal | — | Unable to register Credits Plan on Nevermined | |
| `BCK.COMMON.0007` | 500 | internal | — | Unable to register Time Plan on Nevermined | |
| `BCK.COMMON.0008` | 500 | internal | — | Unable to register Points event in the database | |
| `BCK.COMMON.0009` | 500 | internal | — | Unable to register API Key usage in the database | |
| `BCK.COMMON.0010` | 500 | internal | — | Unable to register AI Agent | |
| `BCK.COMMON.0011` | 500 | internal | — | Unable to register File asset | |
| `BCK.COMMON.0012` | 500 | internal | — | Unable to generate access token to AI Agent | |
| `BCK.COMMON.0013` | 404 | internal | — | Unable to resolve DDO from DID | |
| `BCK.COMMON.0014` | 404 | internal | — | Plan not found | |
| `BCK.COMMON.0015` | 500 | internal | — | Unable to get the Plan balance | |
| `BCK.COMMON.0016` | 500 | internal | — | Unable to order the subscription | |
| `BCK.COMMON.0017` | 500 | internal | — | There are no files associated to the file asset | |
| `BCK.COMMON.0018` | 500 | internal | — | An error happened while downloading the asset files | |
| `BCK.COMMON.0019` | 500 | internal | — | An error happened while trying to mint credits | |
| `BCK.COMMON.0020` | 500 | internal | — | An error happened while trying to burn credits | |
| `BCK.COMMON.0021` | 404 | internal | — | Unable to resolve widget metadata from DID | |
| `BCK.COMMON.0022` | 403 | internal | — | Method not supported | |
| `BCK.COMMON.0023` | 403 | internal | — | Error parsing input | |
| `BCK.COMMON.0024` | 401 | internal | — | Could not validate the login claim | |
| `BCK.COMMON.0025` | 400 | internal | — | Invalid UUID format in request | |
| `BCK.COMMON.0026` | 400 | validation | — | Invalid uint256 identifier (must be a decimal string in \[0, 2^256 - 1]) | |
| `BCK.COMMON.0027` | 409 | business | ❌ | Resource already exists (database unique constraint violated) | A record with the same unique key already exists. Either update the existing record or use a different identifier. |
| `BCK.COMMON.0028` | 409 | business | ❌ | Referenced resource does not exist (foreign key violation) | The request references an entity (plan, agent, user, organisation) that does not exist or has been deleted. Verify the referenced ID. |
| `BCK.COMMON.0029` | 503 | integration | ✅ | Database temporarily unavailable | The database is being restarted or is under maintenance. Retry the request after a short backoff. |
`BCK.CREDITS`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------------- | ---- | -------- | --------- | ------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.CREDITS.0001` | 400 | business | — | Mint amount must be positive | |
| `BCK.CREDITS.0002` | 400 | business | — | Burn amount must be positive | |
| `BCK.CREDITS.0003` | 402 | business | — | Insufficient credits for plan | |
| `BCK.CREDITS.0004` | 400 | business | — | Refund amount must be positive | |
| `BCK.CREDITS.0005` | 500 | business | — | Credit lots do not satisfy the burned amount — FIFO invariant violated | |
| `BCK.CREDITS.0006` | 500 | internal | ❌ | Cannot enqueue on-chain order mirror without a corresponding minted credit lot | enqueueFiatOrderMirror must be called after a successful creditsService.mint with the same sourceTx. This usually indicates an out-of-order call by a service, not a runtime data issue. |
`BCK.DELEGATION`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------------------- | ---- | -------- | --------- | ------------------------ | ----------------------------------------------------------------------------------------- |
| `BCK.DELEGATION.0001` | 404 | business | ❌ | Payment method not found | Verify the paymentMethodId. The payment method may have been removed or never existed. |
| `BCK.DELEGATION.0002` | 404 | business | ❌ | Delegation not found | Verify the delegationId. The delegation may have been revoked, expired, or never existed. |
`BCK.GUEST`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------- | ---- | ---------- | --------- | --------------------------------- | -------------------------------------------------------------------------------------- |
| `BCK.GUEST.0001` | 400 | validation | ❌ | Invalid guest account request | Check the request body — guest provisioning requires either fingerprint or externalId. |
| `BCK.GUEST.0002` | 500 | business | — | Failed to provision guest account | |
`BCK.LEGAL_DOCS`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------------------- | ---- | -------- | --------- | --------------------------------------------------------------------- | ---- |
| `BCK.LEGAL_DOCS.0001` | 404 | business | — | Unknown legal document | |
| `BCK.LEGAL_DOCS.0002` | 404 | business | — | Unknown legal document version | |
| `BCK.LEGAL_DOCS.0003` | 422 | business | — | Submitted legal document version is not the current effective version | |
| `BCK.LEGAL_DOCS.0004` | 412 | business | — | Legal consent is required for the current document versions | |
| `BCK.LEGAL_DOCS.0005` | 401 | business | — | Authenticated request without a resolvable user identity | |
| `BCK.LEGAL_DOCS.0006` | 400 | business | — | No wallet linked to the authenticated Privy account | |
`BCK.METRIC`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------- | ---- | ----------- | --------- | ------------------------------------------- | ---- |
| `BCK.METRIC.0001` | 500 | integration | — | Error registering asset access | |
| `BCK.METRIC.0002` | 404 | integration | — | Error search asset metrics | |
| `BCK.METRIC.0003` | 404 | integration | — | Error getting info from metrics service for | |
| `BCK.METRIC.0004` | 500 | integration | — | Error getting balance for account | |
| `BCK.METRIC.0005` | 500 | integration | — | Error getting total hits for account | |
`BCK.NOTIF`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------- | ---- | ----------- | --------- | ------------------------------------------------------ | ---- |
| `BCK.NOTIF.0001` | 404 | integration | — | Unable to find notification by id | |
| `BCK.NOTIF.0002` | 404 | integration | — | Error searching for notifications | |
| `BCK.NOTIF.0003` | 500 | integration | — | Error updating notification | |
| `BCK.NOTIF.0004` | 500 | integration | — | Error updating notification read status | |
| `BCK.NOTIF.0005` | 500 | integration | — | Error deleting notification | |
| `BCK.NOTIF.0006` | 404 | integration | — | Error searching for notifications filtered by receiver | |
| `BCK.NOTIF.0007` | 500 | integration | — | Resend API Key or Email Sender not set | |
| `BCK.NOTIF.0008` | 500 | integration | — | Error sending email notification | |
| `BCK.NOTIF.0009` | 401 | integration | — | The user doesnt own this notification | |
`BCK.OAUTH`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------- | ---- | -------- | --------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.OAUTH.0001` | 404 | auth | ❌ | OAuth resource not found | Verify the agentId or client identifier in the OAuth request. |
| `BCK.OAUTH.0002` | 400 | auth | ❌ | Invalid OAuth request | Check the request parameters — typically the redirect\_uri, scope, or grant\_type does not match the registered client. Prefer the more specific BCK.OAUTH.0003-0006 siblings at new throw sites. |
| `BCK.OAUTH.0003` | 400 | business | ❌ | No payment plans available for agent | The target agent has no published plans the caller can purchase. Publish a plan first, or pass an explicit plan\_id that the caller already owns. |
| `BCK.OAUTH.0004` | 400 | auth | ❌ | Invalid or expired authorization code | Authorization codes are single-use and short-lived. Restart the flow from /authorize to obtain a fresh code, and ensure the code\_verifier matches the original PKCE code\_challenge. |
| `BCK.OAUTH.0005` | 400 | auth | ❌ | Resource mismatch between token request and authorization code | The `resource` parameter on /token does not match the value bound to the authorization code. Resend with the same `resource` you used on /authorize. |
| `BCK.OAUTH.0006` | 400 | auth | ❌ | User profile not found for the authorization code | The user bound to the authorization code no longer exists in our DB (deleted profile, or environment mismatch). Restart the flow with a valid signed-in user. |
`BCK.OBSERVABILITY`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------------------------- | ---- | ----------- | --------- | ----------------------------------------------- | ---- |
| `BCK.OBSERVABILITY.0001` | 500 | integration | — | Error fetching observability data from Helicone | |
| `BCK.OBSERVABILITY.0002` | 400 | integration | — | Invalid response from Helicone API | |
| `BCK.OBSERVABILITY.0003` | 401 | integration | — | Unauthorized access to Helicone API | |
| `BCK.OBSERVABILITY.0004` | 429 | integration | — | Rate limit exceeded for Helicone API | |
| `BCK.OBSERVABILITY.0005` | 502 | integration | — | Helicone API service unavailable | |
`BCK.ORGANIZATIONS`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------------------------- | ---- | ----------- | --------- | ----------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.ORGANIZATIONS.0001` | 500 | business | — | Error creating organization member | |
| `BCK.ORGANIZATIONS.0002` | 500 | business | — | Error getting organization members | |
| `BCK.ORGANIZATIONS.0003` | 500 | business | — | Error saving organization branding | |
| `BCK.ORGANIZATIONS.0004` | 500 | business | — | Error updating organization | |
| `BCK.ORGANIZATIONS.0005` | 500 | business | — | Error creating organization | |
| `BCK.ORGANIZATIONS.0006` | 500 | business | — | Error creating organization with first admin | The two-step bootstrap (create org + add first admin) failed. Check the underlying error in logs; the org may have been created without the admin link. |
| `BCK.ORGANIZATIONS.0007` | 500 | auth | — | Login failed for organization | |
| `BCK.ORGANIZATIONS.0008` | 403 | business | ❌ | User is already a member of the organization | The membership already exists. Read the membership instead of recreating it, or change the role via the update endpoint. |
| `BCK.ORGANIZATIONS.0009` | 403 | business | ❌ | User is not a member of the organization | Add the user as a member before performing membership-scoped operations. |
| `BCK.ORGANIZATIONS.0010` | 500 | business | — | Failed to update organization member | |
| `BCK.ORGANIZATIONS.0011` | 404 | business | ❌ | Organization not found | Verify the orgId. Soft-deleted organizations also surface as not-found. |
| `BCK.ORGANIZATIONS.0012` | 500 | business | — | Failed to deactivate organization | |
| `BCK.ORGANIZATIONS.0013` | 500 | business | — | Failed to retrieve updated organization | |
| `BCK.ORGANIZATIONS.0014` | 403 | business | ❌ | User already belongs to another organization | A user can only belong to one organization at a time. Remove the user from the current organization before adding them to a new one. |
| `BCK.ORGANIZATIONS.0015` | 500 | integration | ✅ | Failed to look up organization (database error) | Repository.findOne returned a driver/connection error rather than null. Inspect the cause field on the server log; if the database is up, this is likely a query timeout or connection-pool exhaustion. Distinct from BCK.ORGANIZATIONS.0011, which signals a confirmed not-found result. |
`BCK.PAYPAL`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------- | ---- | ----------- | --------- | ------------------------------------------------- | ---- |
| `BCK.PAYPAL.0001` | 500 | integration | — | Unexpected error during PayPal/Braintree checkout | |
`BCK.PLANS`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------- | ---- | -------- | --------- | -------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.PLANS.0001` | 500 | internal | ❌ | Plan lookup failed: plan with the given entryId not found in service layer | The service-layer findOneById returned null. Original behaviour was a generic 500; consumer code that needs 404 semantics should use BCK.PROTOCOL.0003. |
`BCK.POINT`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------- | ---- | -------- | --------- | --------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.POINT.0001` | 401 | business | — | User with address is not allowed to access | |
| `BCK.POINT.0002` | 404 | business | — | User with id not found | |
| `BCK.POINT.0003` | 404 | business | — | Unable to search user points | |
| `BCK.POINT.0004` | 404 | business | — | Unable to search event points | |
| `BCK.POINT.0005` | 404 | business | — | Unable to find user points aggregated | |
| `BCK.POINT.0006` | 404 | business | — | Points rule not found | |
| `BCK.POINT.0007` | 403 | business | ❌ | Points rule recurrency exhausted for user | The rule allows only one (or N) accruals per user; the cap has been reached. |
| `BCK.POINT.0008` | 500 | internal | — | Points rule recurrency type not implemented | |
| `BCK.POINT.0009` | 500 | internal | ❌ | No points rule matches the supplied price/role | The price/role tiers in points.rules.ts are exhaustive for non-negative inputs; reaching this code typically means a negative or otherwise unexpected price was supplied. The status is 500 to preserve the original "throw new Error" behaviour from before #1538; a follow-up (tracked in the Wave-B issue) will demote this to 400 and add input validation at the API boundary. |
| `BCK.POINT.0010` | 403 | business | ❌ | Unsupported points cap recurrency type | The rule references a cap recurrency variant that the engine does not recognise. Update the rule to one of capday/capweek/capmonth. |
| `BCK.POINT.0011` | 403 | business | ❌ | Points rule (onlyonce) already accrued by this user | The rule allows exactly one accrual per user and the user already received their share. No retry will succeed. |
| `BCK.POINT.0012` | 403 | business | ❌ | Points rule (timeslimitted) per-user lifetime cap reached | The rule allows at most rule.cap accruals per (user, rule); the user has reached that ceiling and the cap does not reset. Note: the throw-site `details` line may mention an item reference for historical reasons — the check is per-user, not per-item. Per-item semantics live in BCK.POINT.0013 (onceperitem). |
| `BCK.POINT.0013` | 403 | business | ❌ | Points rule (onceperitem) already accrued for this item | The user already received points for this specific item/reference. Try a different item. |
| `BCK.POINT.0014` | 403 | business | ❌ | Points rule (capday/week/month) time-window cap exhausted | The user reached the cap for this rule within the current time window (day/week/month). Wait for the window to roll over. |
| `BCK.POINT.0015` | 500 | internal | ❌ | No subscription-price points rule for the supplied price | getRuleIdBySubscriptionPrice() saw a price the tier table does not cover — typically a negative value. Add input validation at the API boundary. |
| `BCK.POINT.0016` | 500 | internal | ❌ | No crypto-seller points rule for the supplied price | getRuleIdByCryptoSellerPrice() saw a price the tier table does not cover. |
| `BCK.POINT.0017` | 500 | internal | ❌ | No crypto-buyer points rule for the supplied price | getRuleIdByCryptoBuyerPrice() saw a price the tier table does not cover. |
| `BCK.POINT.0018` | 500 | internal | ❌ | No fiat-seller points rule for the supplied price | getRuleIdByFiatSellerPrice() saw a price the tier table does not cover. |
| `BCK.POINT.0019` | 500 | internal | ❌ | No fiat-buyer points rule for the supplied price | getRuleIdByFiatBuyerPrice() saw a price the tier table does not cover. |
`BCK.PROTOCOL`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------------- | ---- | ----------- | --------- | --------------------------------------------------------------------------------------------------------------------- | ---- |
| `BCK.PROTOCOL.0001` | 500 | integration | — | Unable to register payment plan | |
| `BCK.PROTOCOL.0002` | 500 | integration | — | Unable to register agent | |
| `BCK.PROTOCOL.0003` | 404 | integration | — | Unable to get payment plan by planId | |
| `BCK.PROTOCOL.0004` | 404 | integration | — | Unable to get agent by agentId | |
| `BCK.PROTOCOL.0005` | 500 | integration | — | Error ordering plan | |
| `BCK.PROTOCOL.0006` | 500 | integration | — | Error getting balance of plan | |
| `BCK.PROTOCOL.0007` | 500 | integration | — | Error minting plan | |
| `BCK.PROTOCOL.0008` | 500 | integration | — | Error deleting plan from agent | |
| `BCK.PROTOCOL.0009` | 500 | integration | — | Error adding plan to agent | |
| `BCK.PROTOCOL.0010` | 403 | integration | — | Invalid credits type | |
| `BCK.PROTOCOL.0011` | 403 | integration | — | Insufficient balance | |
| `BCK.PROTOCOL.0012` | 500 | integration | — | Error updating agent | |
| `BCK.PROTOCOL.0013` | 500 | integration | — | Error updating plan | |
| `BCK.PROTOCOL.0014` | 500 | integration | — | Error de-activating agent | |
| `BCK.PROTOCOL.0015` | 500 | integration | — | Error de-activating plan | |
| `BCK.PROTOCOL.0016` | 401 | integration | — | The user doesnt own this agent | |
| `BCK.PROTOCOL.0017` | 401 | integration | — | The user doesnt own this plan | |
| `BCK.PROTOCOL.0018` | 200 | integration | — | The agent is already in the desired state | |
| `BCK.PROTOCOL.0019` | 200 | integration | — | The plan is already in the desired state | |
| `BCK.PROTOCOL.0020` | 500 | integration | — | Error redeming credits | |
| `BCK.PROTOCOL.0021` | 500 | integration | — | Error getting user plans | |
| `BCK.PROTOCOL.0022` | 404 | integration | — | Error getting user agents | |
| `BCK.PROTOCOL.0023` | 404 | integration | — | Error getting plan associated to agent. Agent not found | |
| `BCK.PROTOCOL.0024` | 404 | integration | — | Error getting agent associated to plan. Plan not found | |
| `BCK.PROTOCOL.0025` | 500 | integration | — | Unable to generate agent access token | |
| `BCK.PROTOCOL.0026` | 403 | integration | — | The agent doesnt include the plan specified | |
| `BCK.PROTOCOL.0027` | 403 | integration | — | Unable to validate access token | |
| `BCK.PROTOCOL.0028` | 403 | integration | — | Invalid agent ID in access token | |
| `BCK.PROTOCOL.0029` | 403 | integration | — | Proof is required for this plan | |
| `BCK.PROTOCOL.0030` | 403 | integration | — | Invalid proof | |
| `BCK.PROTOCOL.0031` | 403 | integration | — | Endpoint not included in the agent api | |
| `BCK.PROTOCOL.0032` | 500 | integration | — | Unable to track access transaction | |
| `BCK.PROTOCOL.0033` | 403 | integration | — | You do not have permission to track access transactions for this owner | |
| `BCK.PROTOCOL.0034` | 500 | integration | — | Unable to track access processor queue entry | |
| `BCK.PROTOCOL.0035` | 500 | integration | — | Unable to track agent task | |
| `BCK.PROTOCOL.0036` | 500 | integration | — | Unable to track agent processor queue entry | |
| `BCK.PROTOCOL.0037` | 404 | integration | — | Agent task not found | |
| `BCK.PROTOCOL.0038` | 500 | integration | — | Error updating agent task | |
| `BCK.PROTOCOL.0039` | 500 | integration | — | Error redeeming credits and updating agent task | |
| `BCK.PROTOCOL.0040` | 500 | integration | — | Unable to register agent and plan | |
| `BCK.PROTOCOL.0041` | 403 | integration | — | The user doesnt have a valid Stripe account enabled | |
| `BCK.PROTOCOL.0042` | 403 | integration | — | Either amount or marginPercent must be provided, but not both | |
| `BCK.PROTOCOL.0043` | 403 | integration | — | Plan does not have valid price configuration for margin calculation. Credits type must be DYNAMIC. | |
| `BCK.PROTOCOL.0044` | 404 | integration | — | No Helicone request found for agent request ID | |
| `BCK.PROTOCOL.0045` | 500 | integration | — | Error getting all plans | |
| `BCK.PROTOCOL.0046` | 400 | integration | — | Fiat plan price exceeds the maximum allowed (\$999,999.99). Stripe does not support payment intents above this limit. | |
| `BCK.PROTOCOL.0047` | 400 | integration | — | Fiat plan price is below the minimum allowed (\$1.00). Lower prices do not cover the payment-processor fixed fee. | |
`BCK.STRIPE`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------- | ---- | ----------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.STRIPE.0001` | 400 | integration | — | Error creating Stripe account | |
| `BCK.STRIPE.0002` | 400 | integration | — | Error creating Stripe checkout session | |
| `BCK.STRIPE.0003` | 400 | integration | — | Error creating Stripe payment intent | |
| `BCK.STRIPE.0004` | 500 | integration | — | Error processing Stripe account webhook for updating an account | |
| `BCK.STRIPE.0005` | 400 | integration | — | Error processing Stripe connect webhook | |
| `BCK.STRIPE.0006` | 500 | integration | — | Error processing Stripe checkout event with error | |
| `BCK.STRIPE.0007` | 400 | integration | — | Invalid input params | |
| `BCK.STRIPE.0008` | 400 | integration | — | Stripe event not handled | |
| `BCK.STRIPE.0009` | 400 | integration | — | The plan indicated is not valid for Stripe payment | |
| `BCK.STRIPE.0010` | 400 | integration | — | The plan is not a Fiat plan | |
| `BCK.STRIPE.0011` | 400 | integration | — | Error calculating plan checkout price | |
| `BCK.STRIPE.0012` | 400 | integration | — | The account selling the plan is not properly configured to accept Stripe payments | |
| `BCK.STRIPE.0013` | 400 | integration | — | Payment intent not succeeded | |
| `BCK.STRIPE.0014` | 400 | integration | — | Invalid payment amount from payment intent | |
| `BCK.STRIPE.0015` | 400 | integration | — | Customer not found | |
| `BCK.STRIPE.0016` | 400 | integration | — | Subscription not found | |
| `BCK.STRIPE.0017` | 400 | integration | — | Invoices not found | |
| `BCK.STRIPE.0018` | 400 | integration | — | Error retrieving Stripe payment metadata | |
| `BCK.STRIPE.0019` | 400 | integration | — | Error retrieving Stripe balance | |
| `BCK.STRIPE.0020` | 500 | integration | — | Error canceling subscription | |
| `BCK.STRIPE.0021` | 400 | integration | — | Unable to create Stripe subscription | |
| `BCK.STRIPE.0022` | 424 | integration | — | The settlement could not be executed because the seller account has not properly configured the payment service provider (Stripe) | |
| `BCK.STRIPE.0023` | 503 | integration | — | Transient failure while looking up the seller payment service provider configuration | |
| `BCK.STRIPE.0030` | 500 | integration | — | Application-fee true-up refund failed; row left Settled with the owed amount stored in providerMetadata.trueUpRefundOwedMicro for manual reconciliation | |
| `BCK.STRIPE.0031` | 500 | internal | ❌ | Price conversion overflow when converting micro-units to cents | The plan price exceeds Number.MAX\_SAFE\_INTEGER after conversion. Lower the plan price or fix the unit boundary in convertMicroUnitsToCents. |
| `BCK.STRIPE.0032` | 500 | integration | ❌ | Stripe checkout: user profile not found for account event | The Stripe account event referenced a user that no longer exists in our DB (deleted profile, or environment mismatch between live/sandbox). The webhook is marked permanent so Stripe stops retrying. |
| `BCK.STRIPE.0033` | 500 | integration | ✅ | Stripe account webhook handler failed | Generic catch-all for the account webhook handler — inspect the cause field for the underlying error and the params for eventId/stripeAccountId/userId. |
| `BCK.STRIPE.0034` | 500 | integration | ✅ | Stripe payment intent webhook handler failed | Generic catch-all for the payment intent webhook handler — inspect the cause and params.eventId. |
| `BCK.STRIPE.0035` | 500 | integration | ✅ | Stripe subscription invoice webhook handler failed | Generic catch-all for the subscription invoice (recurring) webhook handler — inspect the cause and params.eventId. |
| `BCK.STRIPE.0036` | 400 | business | ❌ | Stripe subscription creation: plan has no Stripe priceId | The plan DDO is missing metadata.plan.priceId. Re-publish the plan with a Stripe price configured, or use the one-shot payment intent flow. |
| `BCK.STRIPE.0037` | 400 | integration | ✅ | Stripe subscription creation: no latest invoice on subscription | The newly-created subscription did not return a latest\_invoice. Retry once; if it persists, check Stripe dashboard for the subscription state. |
| `BCK.STRIPE.0038` | 400 | integration | ✅ | Stripe subscription creation: no payment intent on subscription | The subscription invoice did not yield a payment\_intent. This usually means the customer has no default payment method. Confirm the SetupIntent has succeeded before creating the subscription. |
`BCK.STRIPE.CONNECT`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------------------------- | ---- | ----------- | --------- | -------------------------------------------------------------- | ---- |
| `BCK.STRIPE.CONNECT.0001` | 503 | integration | — | Stripe Connect is not configured | |
| `BCK.STRIPE.CONNECT.0002` | 400 | integration | — | Stripe OAuth token exchange failed | |
| `BCK.STRIPE.CONNECT.0003` | 400 | integration | — | Stripe OAuth response missing stripe\_user\_id | |
| `BCK.STRIPE.CONNECT.0004` | 400 | integration | — | Stripe account environment does not match platform environment | |
| `BCK.STRIPE.CONNECT.0005` | 404 | integration | — | User profile not found for Stripe Connect update | |
`BCK.TRANSCODING`
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------------------- | ---- | ----------- | --------- | ------------- | ---- |
| `BCK.TRANSCODING.0001` | 404 | integration | — | UGC not found | |
`BCK.TXS`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------- | ---- | ----------- | --------- | --------------------------------------------------- | ---- |
| `BCK.TXS.0001` | 404 | integration | — | Error searching asset transactions by id | |
| `BCK.TXS.0002` | 404 | integration | — | Error searching asset consumer transactions | |
| `BCK.TXS.0003` | 404 | integration | — | Error searching distintc asset transactions | |
| `BCK.TXS.0004` | 404 | integration | — | Error searching plan transactions | |
| `BCK.TXS.0005` | 404 | integration | — | Error searching asset transactions grouped by owner | |
| `BCK.TXS.0006` | 404 | integration | — | Error gathering DDO Info | |
| `BCK.TXS.0007` | 404 | integration | — | Error getting active users for owner | |
| `BCK.TXS.0008` | 404 | integration | — | Error getting total API calls for owner | |
| `BCK.TXS.0009` | 404 | integration | — | Error getting total revenue for owner | |
| `BCK.TXS.0010` | 404 | integration | — | Error getting dashboard metrics for owner | |
`BCK.USER_PROFILE`
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------------------- | ---- | -------- | --------- | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BCK.USER_PROFILE.0001` | 500 | internal | ❌ | User profile not found | Verify the entryId. Note: legacy callers depended on this surfacing as 500; the canonical "user profile not found for caller-supplied identifier" lookup-not-found semantics live in BCK.USER\_PROFILE.0002 (404). |
| `BCK.USER_PROFILE.0002` | 404 | business | ❌ | User profile not found | Verify the user identifier. The profile may have been disabled or never created. |
`BCK.VISA`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------- | ---- | ----------- | --------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `BCK.VISA.0001` | 503 | integration | — | Visa payment provider is not configured | |
| `BCK.VISA.0002` | 502 | integration | — | Visa card enrollment failed | |
| `BCK.VISA.0003` | 502 | integration | — | VGS mandate provisioning failed | VGS rejected `POST /intents` while provisioning the Visa mandate — typically because `assuranceData` is stale, replayed, or doesn't match the spending limit / duration / merchant context shown in the approval prompt. Restart the WebAuthn / passkey device-binding ceremony in the Nevermined webapp to mint a fresh `assuranceData` blob, then retry delegation creation. |
| `BCK.VISA.0004` | 502 | integration | — | VGS cryptogram issuance failed | |
| `BCK.VISA.0005` | 400 | integration | — | Invalid VGS webhook signature | |
| `BCK.VISA.0006` | 502 | integration | — | VGS OAuth2 client\_credentials request failed | |
| `BCK.VISA.0007` | 502 | integration | — | Stripe settlement of Visa virtual card failed | |
| `BCK.VISA.0008` | 400 | integration | — | User has no email on file (required for Visa enrolment) | |
| `BCK.VISA.0009` | 422 | integration | — | Visa mandate (intent) not provisioned for this delegation | |
| `BCK.VISA.0010` | 404 | integration | — | VGS webhook references unknown card | |
| `BCK.VISA.0011` | 400 | integration | — | VGS webhook payload malformed | |
| `BCK.VISA.0012` | 400 | integration | — | VGS webhook revoke event missing card identifier | |
| `BCK.VISA.0013` | 500 | integration | — | Unable to process VGS webhook | |
| `BCK.VISA.0014` | 400 | business | — | Visa delegation creation requires consumerPrompt and assuranceData | Provide both `consumerPrompt` and `assuranceData` when creating a Visa delegation. These are required by the Visa Trusted Agent Protocol and produced by the in-browser VGS Agentic Auth device-binding flow. |
| `BCK.VISA.0015` | 400 | business | — | Visa delegation requires planId — mandate must bind to a single plan seller | Provide `planId` when creating a Visa delegation. Visa mandates must bind to a single plan seller for compliance with the Trusted Agent Protocol. |
| `BCK.VISA.0016` | 400 | business | — | Plan seller has not completed Stripe Connect onboarding required for Visa delegations | The plan seller must complete Stripe Connect onboarding before accepting Visa delegations. Ask the seller to finish onboarding. |
| `BCK.VISA.0017` | 502 | integration | — | Stripe Connect account lookup failed while resolving Visa merchant context | Inspect Stripe dashboard logs for the connected account id in params. Connect account lookup failed transiently — retry; if it persists, check the seller's Connect status. |
| `BCK.VISA.0018` | 409 | business | — | This card is already enrolled to a different account | VGS Agentic Tokens are keyed on PAN globally — the same physical card resolves to the same tokenId regardless of which user enrols it. The card you tried to enrol is already on file under another account. Use a different card. |
| Code | HTTP | Category | Retryable | Message | Hint |
| ------------------------------------------- | ---- | -------- | --------- | ----------------------------------- | ---- |
| `BCK.WIDGET.0001` | 500 | business | — | Unable to store widget config | |
| `BCK.WIDGET.0002` | 404 | business | — | Unable to get widget config from id | |
| `BCK.WIDGET.0003` | 401 | business | — | The user doesnt own this widget | |
| `BCK.WIDGET.0004` | 500 | business | — | Error updating widget config | |
| `BCK.WIDGET.0005` | 500 | business | — | Error deleting widget config | |
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------------------- | ---- | -------- | --------- | ---------------------------- | ---- |
| `BCK.WIDGET_KEYS.0001` | 500 | internal | ❌ | Widget key generation failed | |
| `BCK.WIDGET_KEYS.0002` | 404 | auth | — | Widget key not found | |
| Code | HTTP | Category | Retryable | Message | Hint |
| ----------------------------------------------------------- | ---- | -------- | --------- | ---------------------------------------------------------- | ---- |
| `BCK.WIDGET_SESSION.0001` | 401 | auth | — | Invalid or expired widget init token | |
| `BCK.WIDGET_SESSION.0002` | 401 | auth | — | Organization has no active widget key | |
| `BCK.WIDGET_SESSION.0003` | 500 | auth | — | Widget JWT secret not configured | |
| `BCK.WIDGET_SESSION.0004` | 500 | auth | — | Error creating widget session user | |
| `BCK.WIDGET_SESSION.0005` | 401 | auth | — | Invalid or expired widget session token | |
| `BCK.WIDGET_SESSION.0006` | 500 | auth | — | Widget encryption key not configured or invalid | |
| `BCK.WIDGET_SESSION.0007` | 401 | auth | — | Widget init token is missing required fields | |
| `BCK.WIDGET_SESSION.0008` | 401 | auth | — | Widget session token is missing required wallet claim | |
| `BCK.WIDGET_SESSION.0009` | 401 | auth | — | Widget session token is missing required apiKeyHash claim | |
| `BCK.WIDGET_SESSION.0010` | 401 | auth | — | Widget session token is missing required widgetKeyId claim | |
| `BCK.WIDGET_SESSION.0011` | 401 | auth | — | Widget key has been revoked or no longer exists | |
| `BCK.WIDGET_SESSION.0012` | 403 | auth | — | Origin not allowed for this widget key | |
`BCK.X402`
| Code | HTTP | Category | Retryable | Message | Hint |
| --------------------------------------- | ---- | -------- | --------- | --------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `BCK.X402.0001` | 404 | business | — | Agent not found | |
| `BCK.X402.0002` | 404 | business | — | Plan not found | |
| `BCK.X402.0003` | 400 | business | — | The plan is not associated to the agent | |
| `BCK.X402.0004` | 500 | business | — | Error generating X402 access token | |
| `BCK.X402.0005` | 402 | business | — | Invalid access token | |
| `BCK.X402.0006` | 500 | business | — | Error verifying permissions | |
| `BCK.X402.0007` | 500 | business | — | Failed to order Pay-as-you-go plan | |
| `BCK.X402.0008` | 500 | business | — | Failed to order crypto plan | |
| `BCK.X402.0009` | 500 | business | — | Failed to redeem credits | |
| `BCK.X402.0010` | 400 | business | — | Invalid x402 access token | |
| `BCK.X402.0011` | 404 | business | — | User profile not found | |
| `BCK.X402.0012` | 400 | business | — | resource.url is required when agentId is provided | |
| `BCK.X402.0013` | 400 | business | — | Accepted payment method does not match requirements | |
| `BCK.X402.0014` | 400 | business | — | Delegation restricted to a different plan | |
| `BCK.X402.0015` | 404 | business | ❌ | Permission not found | The permission record either has been revoked or never existed for this combination of (subscriber, plan, agent). |
| `BCK.X402.0016` | 400 | business | ❌ | Permission is already revoked | The permission was already revoked. No further action required. |
| `BCK.X402.0017` | 500 | internal | ❌ | Failed to issue credits after card charge | The card was charged successfully but the DB-side mint of credits failed. The charge is auto-refunded when the provider supports it; otherwise a `failed_post_charge_*` delegationTransactions row is left for manual reconciliation. |