Errors and Troubleshooting

Errors and Troubleshooting

Bakkt provides comprehensive error code documentation to assist clients in swiftly addressing integration and operational issues.

Overview

This guide consolidates error codes and troubleshooting information across multiple Bakkt systems. Refer to the relevant section for your use case:

ACH Return Codes

ACH Return Codes and Their Meanings

Reason CodeExplanation
R01Insufficient funds
R02Account closed
R03Unable to locate account or no account
R04Invalid account number
R05Unauthorized debit to consumer account using Corporate SEC code
R06Returned due to ODFI's request
R07Authorization revoked by customer
R08Payment stopped
R09Uncollected funds
R10Customer advisees unauthorized, improper, ineligible, or part of an incomplete transaction
R11Check Truncation Entry Return
R12Branch sold to another DFI
R13Invalid ACH routing number
R14Representative payee deceased or unable to continue in that capacity
R15Beneficiary or account holder deceased
R16Account frozen/entry returned per OFAC instruction
R17File record edit criteria
R18Improper effective entry date
R19Amount field error
R20Non-Transaction account
R21Invalid company identification
R22Invalid individual ID number
R23Credit entry refused by the receiver
R24Duplicate entry
R25Addenda error
R26Mandatory field error
R27Trace number error
R28Routing number check digit error
R29Corporate customer advises not authorized
R30RDFI not a participant in check truncation program
R31Permissible return entry
R32RDFI non-settlement
R33Return of XCK entry
R34Limited participation DFI
R35Return of improper debit entry
R36Return of improper credit entry
R37Source document presented for payment
R38Stop payment on source document
R39Improper source document or source document presented for payment
R40Return of ENR entry by Federal Government Agency
R41Invalid transaction code
R42Routing number or check digit error
R43Invalid DFI account number
R44Invalid individual id number or identification number
R45Invalid individual name or company name
R46Invalid representative payee indicator
R47Duplicate enrollment

Fiat Funding Onramp Error Codes

Bakkt Transfer API error codes

TypeDescriptionError Explanation
PARTY_SUSPENDEDParty SuspendedThe consumer account is suspended
IDEMPOTENCY_KEY_IN_USEIDEMPOTENCY_KEY_IN_USEIdempotency key was used previously
INVALID_PARTNER_IDThe Partner Id is not validPartnerID is not correct
PARTY_ACCOUNT_NOT_FOUNDPartner Party Ref not foundAn existing consumer account was not found
PARTNER_INVALID_OPERATIONPartner operation not permitted: FUND_TRANSFERPartner account created but does not have service type set up
PARTY_INVALID_OPERATIONParty status not validThe consumer status is not active
PLAID_ACCOUNT_NOT_FOUNDNo active plaid account foundA corresponding Plaid account was not found for the consumer. Bank Link issue
OPERATION_NOT_ALLOWEDAch bank transaction is not allowedThe consumer is not allowed to transfer funds
BANK_ACCOUNT_NOT_FOUNDActive bank account not found for partyNo linked bank account found for Consumer
BANK_LINK_ITEM_NOT_FOUNDNo associated plaid item found for id 34DSFWE456The consumer's Plaid account link may have expired or the user never linked an account
LINKED_BANK_ACCOUNT_NOT_FOUNDActive bank account not found for partyNo linked bank account found for Consumer
BANK_INSTITUTION_NOT_FOUNDFailed to find table PLAID_ITEM record with id 1AFB456The Bank / Institution provided by Plaid cannot be found. A re-link needs to be initiated
UNSUPPORTED_FINANCIAL_INSTITUTIONFinancial Institution provided is unsupported at this time.The consumer Bank is not supported by Bakkt
STORED_AUTH_INVALIDThe current link status is not activePlaid link status is not valid, bank account relinking needed
INVALID_FIELD_VALUEThe amount is below the minimum withdrawal amount of $10.The transaction request amount is below the minimum value
INSUFFICIENT_BALANCEThe account does not have enough available balance for action of value 50 dollarsOperation was rejected because the account had insufficient balance
BANK_ACCOUNT_BLOCKEDThe operation is not allowedThe bank account is on blocked list
BANK_ACCOUNT_BALANCE_UNAVAILABLEBank account provider returned no balance information.No balance account data on bank account
RISKY_EVENT_DECLINEDUnable to process the deposit requestThe event was determined risky and declined
PARTNERPARTYREF_NOT_UNIQUEPartner Party Ref not uniquepartnerPartyRef was used previously
SYSTEM_ERRORSYSTEM_ERRORUnknown error
PARTNER_NOT_IN_HIERARCHYPERMISSION_DENIEDInvalid access
INVALID_PARTNER_STATUSPARTNER_INVAIDInvalid access
TRANSACTION_VELOCITY_OVER_LIMITMaximum number of deposit transactions reachedThe consumer has reached their daily limit for that operation
AMOUNT_OVER_LIMITThe requested amount would exceed the transaction limit.The transaction amount has exceeded the max amount
AMOUNT_OVER_LIMIT_DAILYThe requested amount would exceed the transaction limit.This transaction amount has exceeded daily transaction limit
AMOUNT_OVER_LIMIT_MONTHLYThe requested amount would exceed the transaction limit.This transaction amount has exceeded monthly transaction limit

Bakkt Transaction Retrieval API Error Codes

Http statusTypeSample responseError Explanation
400VALIDATION_ERROR{"type": "VALIDATION_ERROR","description": "Data provided was invalid for operation.","detail": "PARTNER_ID_NOT_VALID_FOR_TRANSACTION"}Invalid PartnerId
400INVALID_DATA{"type": "INVALID_DATA","description": "Data provided was invalid for operation.","detail": "Partner Party Link not found"}Data provided was invalid for operation
400INVALID_OPERATION{"type": "INVALID_OPERATION","description": "Operation is not supported.","detail": "Party operation not permitted: "}Operation is not supported.
400INVALID_OPERATION{"type": "INVALID_OPERATION","description": "Operation is not supported.","detail": "Party status not valid: "}Operation is not supported.
404NOT_FOUND{"type": "NOT_FOUND", "description": "Item is not found for specified id.","detail": "Transaction not found {{transactionId}}"}Item is not found for specified id.

Bakkt Account Link And Add Bank Account API Error Codes

Http statusTypeSample responseError Explanation
400PARTY_INVALID_OPERATION{"type": "PARTY_INVALID_OPERATION","description": "Operation is not supported.","detail": "Party status not valid"}The consumer status is not active
404PARTY_ACCOUNT_NOT_FOUND{"type": "PARTY_ACCOUNT_NOT_FOUND", "description": "Data provided was invalid for operation.", "detail": "Partner Party Ref not found"}An existing consumer account was not found
400INVALID_PARTNER_ID{"type": "INVALID_PARTNER_ID", "description": "Request parameters didn't pass their validation", "detail": "The Partner Id is not valid"}PartnerID is not correct
403LINK_LIMIT_EXCEEDED{"type": "LINK_LIMIT_EXCEEDED", "description": "Link limit exceeded.", "detail": "Link limit exceeded."}Link limit exceeded.
400INVALID_PARTY{"type": "INVALID_PARTY", "description": "Input parameters don't match each other.", "detail": "only parties with a first and last name can link their bank account"}Input parameters don't match each other
500ACCOUNT_ALREADY_LINKED{"type": "ACCOUNT_ALREADY_LINKED","description": "Data provided was invalid for operation","detail": "The account ref has already been linked"}The consumer has already a pending or linked bank account
400ACCOUNT_ALREADY_LINKED{"type": "ACCOUNT_ALREADY_LINKED","description": "Data provided was invalid for operation","detail": "The account ref has already been linked"}The consumer has already a pending or linked bank account
403BANK_ACCOUNT_LINKED_ON_MULTIPLE_PARTIES{"type": "BANK_ACCOUNT_LINKED_ON_MULTIPLE_PARTIES","description": "Linked bank account associated with more than allowed number of party accounts.","detail": "Linked bank account associated with more than allowed number of party accounts."}Linked bank account associated with more than allowed number of party accounts.
403BANK_ACCOUNT_LINKING_DECLINED{"type": "BANK_ACCOUNT_LINKING_DECLINED","description": "Unable to link this bank account.","detail": "BANK_ACCOUNT_LINKING_DECLINED"}Unable to link this bank account, bank account on deny list
400UNSUPPORTED_CURRENCY{"type": "UNSUPPORTED_CURRENCY","description": "Input parameters don't match each other.","detail": "Only USD bank accounts supported"}Non-USD currency, only USD accounts supported
403RISKY_EVENT_DECLINED",{"type": "RISKY_EVENT_DECLINED", "description": "Forbidden.", "detail": "Unable to process the link bank account request."}The event was determined risky and declined
403PARTY_SUSPENDED{"type": "PARTY_SUSPENDED", "description": "Suspended", "detail": "Party Suspended"}The consumer account is suspended
409IDEMPOTENCY_KEY_IN_USE{"type": "IDEMPOTENCY_KEY_IN_USE", "description": "idempotency_key was already used in another request", "detail": "IDEMPOTENCY_KEY_IN_USE"}Idempotency key was used previously
403INVALID_PARTNER_STATUS{"type": "INVALID_PARTNER_STATUS","description": "fobidden","details": "PARTNER_INVAID"}Invalid access
409PARTY_MISMATCH{"type": "PARTY_MISMATCH","description": "Providing user info don't match with existed party.","detail": "Providing user info doesn't match with email or tax id."}Given user info does not match
400VALIDATION_ERROR{"type": "VALIDATION_ERROR","description": "Data provided was invalid for operation.","detail": "INVALID_PARTNER_ID"}Invalid PartnerId
500REMOTE_EXCEPTION{"type": "REMOTE_EXCEPTION","description": "Internal error occurred.","detail": "Risk returned no config."}Internal error performing risk check
500REMOTE_EXCEPTION{"type": "REMOTE_EXCEPTION","description": "Internal error occurred.","detail": "Risk returned no required partner party level."}Internal error performing risk check
400VALIDATION_ERROR{"type": "VALIDATION_ERROR","description": "Request parameters didn't pass their validation, see errordetails.","detail": "Party \ already closed."}Internal error suspending party after KYC failure. Consumer account \ already closed.
400DATA_MISMATCH{"type": "DATA_MISMATCH","description": "Input parameters don't match each other.","detail": "party already suspended"}Internal error suspending party after KYC failure. Consumer already suspended
500API_ERROR{"type": "API_ERROR", "description": "Intenal error occurred.", "detail": "AGP api failed"}Internal error suspending party after KYC failure. API failed
500RPC_FAILED{"type": "RPC_FAILED", "description": "Internal error occurred.", "detail": "failed to retrieve party to delete a party role"}Internal error suspending party after KYC failure
500RPC_FAILED{"type": "RPC_FAILED", "description": "Internal error occurred.", "detail": "failed to delete a party"}Internal error suspending party after KYC failure. Failed to rerieve party
500RPC_FAILED{"type": "RPC_FAILED", "description": "Internal error occurred.", "detail": "failed to retrieve party to add a party role"}Internal error suspending party after KYC failure
500RPC_FAILED{"type": "RPC_FAILED", "description": "Internal error occurred.", "detail": "failed to add a party role"}Internal error suspending party after KYC failure
400FORBIDDEN_ACCOUNT{"type": "FORBIDDEN_ACCOUNT", "description": "Existing account is suspended or blocked", "detail": "Party is suspended or blocked"}Party is suspended
500FORBIDDEN_ACCOUNT{"type": "FORBIDDEN_ACCOUNT", "description": "Existing account is suspended or blocked", "detail": "Party is liquidated"}Party is liquidated

Bakkt Link URL Error Codes

Reason CodeError Explanation
link_expiredThe embedded Link url has expired
session_expiredUser session within the link has expired
bank_not_supportedBank is not supported at Bakkt
user_cancelledUser cancelled bank linking process
plaid_bank_link_failureThe bank linking experience failed on Plaid
bakkt_bank_link_failureBank linking failed on Bakkt. This could happen for different reasons
  • User is Suspended
  • Risk check at Bakkt failed
  • Identity or Auth check at Plaid failed
  • Bank account linking velocity limit reached at Bakkt

API Order Reject Reasons

Reject ReasonsDescription
unknown: empty quotesYou may get this when trying to places orders when the digital asset system does not have a price for the symbol in your order.
unknown: trade quantity exceeds position sideYou will get this when you try to sell more coin than what the BFS system believes you have.
internal: Could not retrieve jurisdiction status for correspondent accountWhen an account does not have a valid jurisdiction e.g. state of ZZ or the jurisdiction status that this has account is not referenced in BFS systems.
price too far through marketWhen you try and place an order more than 10% away from the market we will reject it. It is based on the wrong side of the market, you can't place a limit sell that's 10% lower than the current bid and can't place a limit buy that's 10% higher than the current ask.
invalid_argument: live_till Order expiredWhen you try to place an order during the BFS maintenance window (16:30-17:05 CT) you will receive these.
failed_precondition: unable to trade due to 'NY' allowing CLOSE onlyAttempting to place a Buy order from a jurisdiction that is not enabled for purchasing digital assets on that symbol.
invalid_argument: price may not place orders of XLMUSD with more than 4 decimal places, had 6The order placed has too many decimal places for price for specified Symbol.
invalid_argument: quantity order notional must be more than $1.00 unless selling out entire positionThis happens when you try to buy or sell < $1 of coin. BFS only allows below that limit when you are selling an entire position.

Gifting Error Codes

If any data validations fail, the request gets a response with a REJECTED status along with a text string explaining the reject reason. The following table provides the most common reasons for gift request rejections.

Error ScenarioRejection/Error Message
Account does not existInvalid account Id
Inventory Account does not existThe Gift Account does not exist for this client
Client submits the same clientTransactionId more than onceDuplicate clientTransactionId; the allocation request already exists
Currency does not existInvalid currency
Inventory unavailable for requested currencyInsufficient inventory to allocate the requested currency
The clientTransactionId does not exists (when retrieving allocation details)Invalid clientTransactionId

Batch Trade & Allocation Error Codes

See the following list for the most common errors and allocation reject reasons.

Error and Reject Scenarios
Customer account does not exist
Firm Allocation Account does not exist
Submitting the same clientTransactionId more than once
Symbol mismatches symbol of batch (when allocating to a batch)
Batch ID does not exist (when allocating to/retrieving from batch)
Allocations count mismatch (when closing batch)
Investor account does not have enough digital assets to sell
The clientTransactionId does not exist (when retrieving allocation details)
Symbol does not exist
Allocation amount (either notional or quantity) is negative

Did this page help you?