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
- Fiat Funding Onramp Error Codes
- API Order Reject Reasons
- Gifting Error Codes
- Batch Trade & Allocation Error Codes
ACH Return Codes
ACH Return Codes and Their Meanings
| Reason Code | Explanation |
|---|---|
| R01 | Insufficient funds |
| R02 | Account closed |
| R03 | Unable to locate account or no account |
| R04 | Invalid account number |
| R05 | Unauthorized debit to consumer account using Corporate SEC code |
| R06 | Returned due to ODFI's request |
| R07 | Authorization revoked by customer |
| R08 | Payment stopped |
| R09 | Uncollected funds |
| R10 | Customer advisees unauthorized, improper, ineligible, or part of an incomplete transaction |
| R11 | Check Truncation Entry Return |
| R12 | Branch sold to another DFI |
| R13 | Invalid ACH routing number |
| R14 | Representative payee deceased or unable to continue in that capacity |
| R15 | Beneficiary or account holder deceased |
| R16 | Account frozen/entry returned per OFAC instruction |
| R17 | File record edit criteria |
| R18 | Improper effective entry date |
| R19 | Amount field error |
| R20 | Non-Transaction account |
| R21 | Invalid company identification |
| R22 | Invalid individual ID number |
| R23 | Credit entry refused by the receiver |
| R24 | Duplicate entry |
| R25 | Addenda error |
| R26 | Mandatory field error |
| R27 | Trace number error |
| R28 | Routing number check digit error |
| R29 | Corporate customer advises not authorized |
| R30 | RDFI not a participant in check truncation program |
| R31 | Permissible return entry |
| R32 | RDFI non-settlement |
| R33 | Return of XCK entry |
| R34 | Limited participation DFI |
| R35 | Return of improper debit entry |
| R36 | Return of improper credit entry |
| R37 | Source document presented for payment |
| R38 | Stop payment on source document |
| R39 | Improper source document or source document presented for payment |
| R40 | Return of ENR entry by Federal Government Agency |
| R41 | Invalid transaction code |
| R42 | Routing number or check digit error |
| R43 | Invalid DFI account number |
| R44 | Invalid individual id number or identification number |
| R45 | Invalid individual name or company name |
| R46 | Invalid representative payee indicator |
| R47 | Duplicate enrollment |
Fiat Funding Onramp Error Codes
Bakkt Transfer API error codes
| Type | Description | Error Explanation |
|---|---|---|
| PARTY_SUSPENDED | Party Suspended | The consumer account is suspended |
| IDEMPOTENCY_KEY_IN_USE | IDEMPOTENCY_KEY_IN_USE | Idempotency key was used previously |
| INVALID_PARTNER_ID | The Partner Id is not valid | PartnerID is not correct |
| PARTY_ACCOUNT_NOT_FOUND | Partner Party Ref not found | An existing consumer account was not found |
| PARTNER_INVALID_OPERATION | Partner operation not permitted: FUND_TRANSFER | Partner account created but does not have service type set up |
| PARTY_INVALID_OPERATION | Party status not valid | The consumer status is not active |
| PLAID_ACCOUNT_NOT_FOUND | No active plaid account found | A corresponding Plaid account was not found for the consumer. Bank Link issue |
| OPERATION_NOT_ALLOWED | Ach bank transaction is not allowed | The consumer is not allowed to transfer funds |
| BANK_ACCOUNT_NOT_FOUND | Active bank account not found for party | No linked bank account found for Consumer |
| BANK_LINK_ITEM_NOT_FOUND | No associated plaid item found for id 34DSFWE456 | The consumer's Plaid account link may have expired or the user never linked an account |
| LINKED_BANK_ACCOUNT_NOT_FOUND | Active bank account not found for party | No linked bank account found for Consumer |
| BANK_INSTITUTION_NOT_FOUND | Failed to find table PLAID_ITEM record with id 1AFB456 | The Bank / Institution provided by Plaid cannot be found. A re-link needs to be initiated |
| UNSUPPORTED_FINANCIAL_INSTITUTION | Financial Institution provided is unsupported at this time. | The consumer Bank is not supported by Bakkt |
| STORED_AUTH_INVALID | The current link status is not active | Plaid link status is not valid, bank account relinking needed |
| INVALID_FIELD_VALUE | The amount is below the minimum withdrawal amount of $10. | The transaction request amount is below the minimum value |
| INSUFFICIENT_BALANCE | The account does not have enough available balance for action of value 50 dollars | Operation was rejected because the account had insufficient balance |
| BANK_ACCOUNT_BLOCKED | The operation is not allowed | The bank account is on blocked list |
| BANK_ACCOUNT_BALANCE_UNAVAILABLE | Bank account provider returned no balance information. | No balance account data on bank account |
| RISKY_EVENT_DECLINED | Unable to process the deposit request | The event was determined risky and declined |
| PARTNERPARTYREF_NOT_UNIQUE | Partner Party Ref not unique | partnerPartyRef was used previously |
| SYSTEM_ERROR | SYSTEM_ERROR | Unknown error |
| PARTNER_NOT_IN_HIERARCHY | PERMISSION_DENIED | Invalid access |
| INVALID_PARTNER_STATUS | PARTNER_INVAID | Invalid access |
| TRANSACTION_VELOCITY_OVER_LIMIT | Maximum number of deposit transactions reached | The consumer has reached their daily limit for that operation |
| AMOUNT_OVER_LIMIT | The requested amount would exceed the transaction limit. | The transaction amount has exceeded the max amount |
| AMOUNT_OVER_LIMIT_DAILY | The requested amount would exceed the transaction limit. | This transaction amount has exceeded daily transaction limit |
| AMOUNT_OVER_LIMIT_MONTHLY | The requested amount would exceed the transaction limit. | This transaction amount has exceeded monthly transaction limit |
Bakkt Transaction Retrieval API Error Codes
| Http status | Type | Sample response | Error Explanation |
|---|---|---|---|
| 400 | VALIDATION_ERROR | {"type": "VALIDATION_ERROR","description": "Data provided was invalid for operation.","detail": "PARTNER_ID_NOT_VALID_FOR_TRANSACTION"} | Invalid PartnerId |
| 400 | INVALID_DATA | {"type": "INVALID_DATA","description": "Data provided was invalid for operation.","detail": "Partner Party Link not found"} | Data provided was invalid for operation |
| 400 | INVALID_OPERATION | {"type": "INVALID_OPERATION","description": "Operation is not supported.","detail": "Party operation not permitted: "} | Operation is not supported. |
| 400 | INVALID_OPERATION | {"type": "INVALID_OPERATION","description": "Operation is not supported.","detail": "Party status not valid: "} | Operation is not supported. |
| 404 | NOT_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 status | Type | Sample response | Error Explanation |
|---|---|---|---|
| 400 | PARTY_INVALID_OPERATION | {"type": "PARTY_INVALID_OPERATION","description": "Operation is not supported.","detail": "Party status not valid"} | The consumer status is not active |
| 404 | PARTY_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 |
| 400 | INVALID_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 |
| 403 | LINK_LIMIT_EXCEEDED | {"type": "LINK_LIMIT_EXCEEDED", "description": "Link limit exceeded.", "detail": "Link limit exceeded."} | Link limit exceeded. |
| 400 | INVALID_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 |
| 500 | ACCOUNT_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 |
| 400 | ACCOUNT_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 |
| 403 | BANK_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. |
| 403 | BANK_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 |
| 400 | UNSUPPORTED_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 |
| 403 | RISKY_EVENT_DECLINED", | {"type": "RISKY_EVENT_DECLINED", "description": "Forbidden.", "detail": "Unable to process the link bank account request."} | The event was determined risky and declined |
| 403 | PARTY_SUSPENDED | {"type": "PARTY_SUSPENDED", "description": "Suspended", "detail": "Party Suspended"} | The consumer account is suspended |
| 409 | IDEMPOTENCY_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 |
| 403 | INVALID_PARTNER_STATUS | {"type": "INVALID_PARTNER_STATUS","description": "fobidden","details": "PARTNER_INVAID"} | Invalid access |
| 409 | PARTY_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 |
| 400 | VALIDATION_ERROR | {"type": "VALIDATION_ERROR","description": "Data provided was invalid for operation.","detail": "INVALID_PARTNER_ID"} | Invalid PartnerId |
| 500 | REMOTE_EXCEPTION | {"type": "REMOTE_EXCEPTION","description": "Internal error occurred.","detail": "Risk returned no config."} | Internal error performing risk check |
| 500 | REMOTE_EXCEPTION | {"type": "REMOTE_EXCEPTION","description": "Internal error occurred.","detail": "Risk returned no required partner party level."} | Internal error performing risk check |
| 400 | VALIDATION_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. |
| 400 | DATA_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 |
| 500 | API_ERROR | {"type": "API_ERROR", "description": "Intenal error occurred.", "detail": "AGP api failed"} | Internal error suspending party after KYC failure. API failed |
| 500 | RPC_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 |
| 500 | RPC_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 |
| 500 | RPC_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 |
| 500 | RPC_FAILED | {"type": "RPC_FAILED", "description": "Internal error occurred.", "detail": "failed to add a party role"} | Internal error suspending party after KYC failure |
| 400 | FORBIDDEN_ACCOUNT | {"type": "FORBIDDEN_ACCOUNT", "description": "Existing account is suspended or blocked", "detail": "Party is suspended or blocked"} | Party is suspended |
| 500 | FORBIDDEN_ACCOUNT | {"type": "FORBIDDEN_ACCOUNT", "description": "Existing account is suspended or blocked", "detail": "Party is liquidated"} | Party is liquidated |
Bakkt Link URL Error Codes
| Reason Code | Error Explanation |
|---|---|
| link_expired | The embedded Link url has expired |
| session_expired | User session within the link has expired |
| bank_not_supported | Bank is not supported at Bakkt |
| user_cancelled | User cancelled bank linking process |
| plaid_bank_link_failure | The bank linking experience failed on Plaid |
| bakkt_bank_link_failure | Bank 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 Reasons | Description |
|---|---|
| unknown: empty quotes | You 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 side | You 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 account | When 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 market | When 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 expired | When 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 only | Attempting 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 6 | The 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 position | This 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 Scenario | Rejection/Error Message |
|---|---|
| Account does not exist | Invalid account Id |
| Inventory Account does not exist | The Gift Account does not exist for this client |
Client submits the same clientTransactionId more than once | Duplicate clientTransactionId; the allocation request already exists |
| Currency does not exist | Invalid currency |
| Inventory unavailable for requested currency | Insufficient 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 |
Updated about 1 month ago
Did this page help you?
