Documentation Index
Fetch the complete documentation index at: https://docs.nevermined.app/llms.txt
Use this file to discover all available pages before exploring further.
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
| 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. |
