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 — 11 codes
• BCK.APIKEY — 12 codes
• BCK.AUTH — 9 codes
• BCK.BRAINTREE — 9 codes
• BCK.COMMON — 29 codes
• BCK.CREDITS — 6 codes
• BCK.DELEGATION — 2 codes
• BCK.GUEST — 2 codes
• BCK.LEGAL_DOCS — 6 codes
• BCK.METRIC — 5 codes
• BCK.NOTIF — 9 codes
• BCK.OAUTH — 6 codes
• BCK.OBSERVABILITY — 5 codes
• BCK.ORGANIZATIONS — 15 codes
• BCK.PAYPAL — 1 code
• BCK.PLANS — 1 code
• BCK.POINT — 19 codes
• BCK.PROTOCOL — 47 codes
• BCK.STRIPE — 32 codes
• BCK.STRIPE.CONNECT — 5 codes
• BCK.TRANSCODING — 1 code
• BCK.TXS — 10 codes
• BCK.USER_PROFILE — 2 codes
• BCK.VISA — 18 codes
• BCK.WIDGET — 5 codes
• BCK.WIDGET_KEYS — 2 codes
• BCK.WIDGET_SESSION — 12 codes
• 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.

BCK.WIDGET

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

BCK.WIDGET_KEYS

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

BCK.WIDGET_SESSION

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.