Response codes

The Core API uses standard HTTP response codes to indicate the status of requests. In general: codes in the 2xx range indicate success; codes in the 4xx range indicate an error in the request; and codes in the 5xx range indicate an error at the Marqeta platform. The following table shows some common response codes:

Response Code Description
200 OK Your request completed successfully.
201 Created Resource created successfully.
204 No Content Returned on a successful DELETE.
401 Unauthorized
403 Forbidden
405 Method Not Allowed The method you supplied is not allowed for that resource, for example a PUT method on a read-only resource.
413 Request Entity Too Large The request body is too large or the GET request count parameter is too large.
422 Velocity rules violation or non-sufficient funds
500 Internal Server Error An error occurred that could not be handled by the application.
502 Bad Gateway
503 Service Unavailable
504 Gateway Timeout

If a POST or PUT request causes a validation failure, the Marqeta platform returns a response code of 400 and a body containing details about the exception. For example, a request to associate a card with a non-existent card product returns the following response body:

{
"bad request": "Card product not found."
}


Error codes and messages

Error codes are based on HTTP response codes. The first three digits include the HTTP response code and the last three digits represent the error.

Common error codes 400

Error Code Error Message
400001 Invalid input(s) detected: x, y, z
400002 Birth date cannot be a future date
400003 Start date cannot be greater than or equal to end date
400004 One or more invalid field(s) have been detected: x, y, z
400005 An invalid currency code has been detected
400006 Amount must be greater than or equal to 0
400007 There is nothing to update. All fields are null
400008 Missing a required field
400009 Issuer not found
400010 Cardholder not found
400011 Store not found
400012 Merchant not found
400013 Card not found
400014 Order not found
400015 Campaign not found
400016 Card product not found
400017 Funding account not found
400018 Program account not found
400019 Fee not found
400020 Offer not found
400021 Rule not found
400022 Authentication user not found
400023 Reward program token not found or is not active
400024 Reward token not found
400025 Auth control not found
400026 User token is invalid
400027 Velocity control not found
400028 Auto reload not found
400029 Unknown Error
400030 MCC group not found
400031 Invalid cardholder
400032 Invalid address
400033 Offer already exists
400034 One or more fields have invalid length
400035 Maximum number of children
400036 General input exception: x
400037 Malformed JSON request received
400038 General gateway exception: x
400039 Deposit Account not found
400040 Direct Deposit not found
400041 Card product not found or not active
400042 Invalid sort field passed
400043 Invalid date format received
400044 Invalid start date format received
400045 Invalid end date format received
400046 Chargeback not found
400047 Cardholder does not have full SSN
400048 Request object cannot be empty
400049 Digital wallet token not found
400575 User token and Business token may not be both populated
400576 User token and Business token must be populated
400675 Original transaction not found
400676 Unable to reverse transaction due to ITC
400677 Account holder group not found
400678 Index out of range
400679 Reference transaction not found or does not associate to the original card
400680 The funding source cannot be set as default
400681 The package Id does not belong to any card product
400682 Invalid chargeback state has been detected
400683 Commando mode not found
400684 Program funding source not found
400685 Program gateway funding source not found
400686 Network tran group not found
400687 Network tran type not found

Common error codes 401

Error Code Error Message
401001 Invalid credential has been detected

Common error codes 403

Error Code Error Message
403001 User does not have permission to access this endpoint

Common error codes 404

Error Code Error Message
404000 Resource not found or unavailable

Common error codes 405

Error Code Error Message
405001 Resource not available

Common error codes 409

Error Code Error Message
409001 Resource not available
409002 General conflict exception: x

Common error codes 422

Error Code Error Message
422001 Insufficient funds
422002 General unprocessible exception: x
422003 Unsuccessful response from token services gateway:

Common error codes 500

Error Code Error Message
500000 Internal server error

Accepted Countries endpoints 400

Error Code Error Message
400510 Country Codes missing

Accepted Countries endpoints 404

Error Code Error Message
404500 Accepted Country not found

Account Holder Groups endpoints 404

Error Code Error Message
404525 Account holder group not found

Account Holder Groups endpoints 422

Error Code Error Message
422125 Unable to exceed max balance
422126 Non program funding source load is not allowed
422127 Reloads are not allowed

Auth Controls / Velocity Controls / KYC endpoints 400

Error Code Error Message
400150 Auth restriction not found
400151 Velocity profile not found
400152 Required fields for a user cannot be empty: x, y
400153 Only either of mid OR mcc OR mcc_group is permitted
400155 KYC Provider not setup
400156 Spend control can not be applied to a business
400157 This endpoint is reserved for User Cardholder KYCS only
400158 Required fields for a business cannot be empty: x, y
400159 KYC not permitted for card holder with a P.O Box address
400160 number_of_days and velocity_window may not both be populated
400163 number_of_days or velocity_window must be populated
400164 reference_id may only be used for a manual override
400172 Cardholder name must contain only alpha characters
400173 Cannot set number_of_days for velocity control with velocity_window
400174 Invalid input(s): Cannot set usage_limit when velocity_window is TRANSACTION

Auth Controls / Velocity Controls / KYC endpoints 404

Error Code Error Message
404075 KYC not found
404076 Cardholder has no KYC objects associated
404077 Auth control not found
404078 Velocity control not found
404079 Invalid additional transaction data format

Auth Controls / Velocity Controls / KYC endpoints 409

Error Code Error Message
409010 Auth control default acceptance behavior has not been set
409011 Card product token is invalid
409012 User token is invalid
409013 Duplicate KYC token

Auth Controls / Velocity Controls / KYC endpoints 500

Error Code Error Message
500175 Error returned from KYC provider

Auto Reload endpoints 400

Error Code Error Message
400400 Maximum result limit exceeded
400401 Funding source token required
400402 Funding source not found
400403 Funding address token missing
400404 Order scope not found
400405 Auto reload of the same type already exists
400406 Funding address not found
400407 Only card_product_token OR card_holder_token is permitted
400408 Invalid reload to amount. The amount must be at least 0.01
400409 Invalid trigger amount. The amount must be at least 0.01
400410 Cannot attach funding source that belongs to a cardholder
400411 Funding address does not belong to cardholder
400412 Funding source does not belong to the cardholder
400413 Funding source not found or it is not allowed to be used in the current context
400414 Trigger amount is greater than reload amount
400415 GPA is required

Auto Reload endpoints 404

Error Code Error Message
404325 Auto reload not found

Bulk Issuance endpoints 400

Error Code Error Message
400161 Inventory user token is required when single inventory user flag is true
400162 Single inventory user flag should be true if inventory user token is passed
400165 Name line 1 is required
400166 Name line 1 cannot be more than 14 characters
400167 Name line can contain only alpha numeric characters
400168 Bulk ship should be enabled for bulk issuance card product
400169 Recipient address needs to be defined at at least one of Card Product or Bulk Issuance
400170 Cannot update expedite flag for a processed bulk issuance
400171 Cannot update fulfillment information for a processed bulk issuance
400706 Invalid shipping method for bulk order. Choose STANDARD_NEXT_DAY, PRIORITY_NEXT_DAY, or GROUND
400707 Invalid shipping method for bulk order. Choose STANDARD_NEXT_DAY or GROUND

Bulk Issuance endpoints 404

Error Code Error Message
404160 Bulk issuance request not found

Businesses endpoints 400

Error Code Error Message
400550 Business may not hold card
400551 Invalid date established format received
400552 Invalid incorporation type
400553 Business is not active

Businesses / Business Transitions endpoints 400

Error Code Error Message
400751 Cannot transition business to ACTIVE until it has passed KYC
400753 Cannot transition business from UNVERIFIED to SUSPENDED
400755 Cannot transition business to LIMITED until it has passed KYC

Businesses / Business Transitions endpoints 404

Error Code Error Message
404500 Business not found
404532 Business transition not found

Campaigns endpoints 400

Error Code Error Message
400175 Campaign contains one or more active orders
400176 Campaign is not active

Campaigns endpoints 404

Error Code Error Message
404100 Campaign not found

Campaigns endpoints 409

Error Code Error Message
409025 Cannot delete a default merchant campaign
409026 Cannot update a default merchant campaign

Card Products endpoints 400

Error Code Error Message
400200 Card product with token does not allow for merchant onboarding
400201 Card product with the same token already exists
400202 config.jit_funding.programgateway_funding_source.funding_source_token is required
400203 config.jit_funding.programgateway_funding_source.funding_source_token is invalid
400204 Invalid BIN Prefix. Only 111111 is allowed
400205 Min offset cannot be greater than default offset
400206 Can only have one enabled JIT Funding Source

Card Products endpoints 404

Error Code Error Message
404125 Card product not found

Cards/Card Transitions/Digital Wallet Tokens endpoints 400

Error Code Error Message
400074 Max card orders per day limit reached
400075 Card already exists
400076 Either the phone number or last four of SSN is required
400077 Birth date entered does not match the record
400078 SSN missing on record
400079 Invalid SSN detected
400080 Phone number entered does not match the record
400081 Last four of SSN does not match the record
400082 User token, phone and date of birth must be presented
400083 Phone number or date of birth does not match the record
400084 No active card found for user
400085 cvv_number does not match
400086 Expiration does not match
400087 A card with the same merchant token already exists in the system
400088 Merchant card not found
400089 Cannot move an active card to a new cardholder
400090 The card is already in terminated state
400091 Only an unactivated or suspended card can be activated
400092 Only an activated card can be suspended
400093 Cannot unactivate a card
400094 Last four of PAN is required
400095 Invalid card transition state
400096 Card token cannot start with reserved keyword
400097 Unable to generate card verification value
400098 Bulk card order must be unprocessed
400099 Card product must equal bulk card order card product
400650 Invalid digital wallet token transition state
400651 Cannot unactivate a digital wallet token
400652 The digital wallet token is already in terminated state
400653 Only suspended or requested digital wallet token can be activated
400654 Only an active digital wallet token can be suspended
400655 The digital wallet token cannot be terminated
400656 The card must be active or unactivated
400657 Card is expired
400658 Recipient address needs to be defined at at least one of Card, Card Holder or Card Product
400659 Unable to create card when allow_card_creation is set to false
400660 Cannot update expedite flag for a fulfilled card
400661 Cannot update fulfillment information for a fulfilled card
400664 When reissuing a pan from card token is set, pin translation from card token not allowed. For reissue, the card pin will be translated automatically.
400665 Pin translation card token does not exist or card does not belong to the same user
400666 Swap digital wallet tokens from card token does not exist
400667 Unable to translate pin to new card
400668 The reissued card can not be converted from physical to virtual card
400669 Token transition not allowed, awaiting activation by token service provider
400670 No cards found for a given reissued card token
400671 The reissue source card must be latest active or suspended card in the chain
400672 The reissue source card must be ACTIVE or SUSPENDED
400673 Max card orders allowed by inventory has been reached
400683 Expiration offset must be within window defined in card product
400691 Card may not be created with a bulk ship enabled Card Product that has no recipient address
400692 Card may not be created with bulk ship enabled Card Product which is missing recipient address first or last name
400693 User not allowed to tokenize old reissued card
400694 Image names in card personalization cannot contain spaces
400695 Image names in card personalization require PNG extension
400696 Image names in card personalization should be unique
400697 reason_code must be populated
400698 Endpoint is no longer valid. Please use card transitions
400704 Invalid shipping method for non-expedited order. Choose USPS_REGULAR
400705 Invalid shipping method for expedited order. Choose STANDARD_NEXT_DAY, PRIORITY_NEXT_DAY, or GROUND

Cards/Card Transitions/Digital Wallet Tokens endpoints 404

Error Code Error Message
404001 Card not found
404002 Card transition not found
404003 Merchant card not found
404004 Cardholder not found
404005 Digital wallet token transition not found

Cards/Card Transitions/Digital Wallet Tokens endpoints 412

Error Code Error Message
412003 Missing program Id setup error

Cards/Card Transitions/Digital Wallet Tokens endpoints 422

Error Code Error Message
422015 Unable to create Card for a User that has not passed KYC

Chargebacks endpoints 400

Error Code Error Message
400450 Reference network does not contain a valid network
400451 Invalid network detected
400452 Chargeback cannot exceed authorization amount
400453 Chargeback not allowed on this transaction type
400454 Chargeback state is the same as previous
400456 Chargeback is already at terminal state
400457 Chargeback created by gateway channel cannot be set to Network Rejected
400458 Chargeback transition is unable to represent the original auth
400459 Chargebacks not allowed on this transaction type when channel is issuer
400460 Chargebacks not allowed on this transaction type when channel is gateway
400461 The original transaction is not related to an MSA order
400462 Chargeback network submission not found
400463 Not allowed to update network submission time on chargeback network submission as it was never submitted to network
400464 Not allowed to update network submission time on chargeback network submission more than once
400465 Not allowed to move chargeback from Representment state to Case Won
400466 Maximum chargebacks allowed per card limit reached
400467 Chargeback cannot be moved to prearbitration from initiated
400468 Unable to reverse provisional credit for chargeback
400469 Unable to grant provisional credit for chargeback
400470 Chargeback cannot be set to non written off state
400471 Chargeback cannot be set to written off state
400472 Either reason description or reason code must be set
400473 Invalid chargeback state
400474 Chargeback cannot be transition to representment without the amount

Chargebacks endpoints 403

Error Code Error Message
403010 User is forbidden to set chargeback to written off states

Chargebacks endpoints 404

Error Code Error Message
404350 Chargeback not found
404351 Chargeback transition not found

Chargebacks endpoints 412

Error Code Error Message
412025 Chargeback amount has exceeded GPA balance
412026 Chargeback amount has exceeded MSA balance

Chargebacks endpoints 422

Error Code Error Message
422075 The initiated chargeback is not associated to a transaction

Chargebacks endpoints 500

Error Code Error Message
500109 There was a problem with retrieving a chargeback
500110 There was a problem with retrieving a chargeback transition
500111 There was a problem with creating a chargeback transition
500112 There was a problem with retrieving chargeback network submissions
500113 There was a problem with updating chargeback network submission
500114 There was a problem with granting provisional credit for a chargeback
500115 There was a problem with reversing provisional credit for a chargeback
500116 There was a problem with retrieving transitions for a commandomode
500117 There was a problem with retrieving a commandomode
500118 There was a problem with creating transitions for a commandomode
500119 There was a problem creating a direct deposit
500120 There was a problem creating a direct deposit transition
500121 There was a problem retrieving a direct deposit transition

Commando Mode endpoints 400

Error Code Error Message
400700 Unable to transition the commando mode to the same state
400701 Only one commando mode allowed per program gateway funding source

Commando Mode endpoints 404

Error Code Error Message
404575 Commando mode transition not found
404576 Commando mode not found

Commando Mode endpoints 422

Error Code Error Message
422150 Commando mode cannot be updated due to its current state

Digital Wallet Token endpoints 500

Error Code Error Message
404456 Digital wallet token not found
400500 In-App Provision not allowed for a given card
400800 Invalid Network
400801 Digital wallet token is already active

File processing error codes 404

Error Code Error Message
404530 File processing not found

Funding Sources / Funding Addresses / Fees / Real Time Fee Groups/ Direct Deposit endpoints 400

Error Code Error Message
400225 Could not find a valid funding source
400226 Please provide a valid funding source address token
400227 This endpoint can be called only for Payment Card
400228 Invalid type. Use type=paymentcard or type=ach
400229 No referenced original authorization found
400230 No such GPA_PENDING_CREDIT tranlog found
400231 Real time fee group not found
400232 Missing apply to transaction type in the fee being added to the group
400233 Cannot have multiple fees with same apply transaction type in the group
400234 Invalid transaction type in the fee being added to group
400235 An existing deposit account has already been created for the user
400237 Cannot set the same state
400238 Cannot set state to approved pending from approved credited
400239 Cannot update a processed rejected record
400240 Funding account not active
400241 Unsupported batch header
400242 Unsupported detail record: 
400243 Malformed batch header and/or malformed detail record
400244 URL protocols must be https
400245 ACH account already verified
400247 The payment card that you have entered is not permitted to be registered as a funding source
400248 program_reserve_token must be populated if owner_type is PROGRAM
400249 owner_type must be PROGRAM if program_reserve_token is populated
400260 Direct deposit is already in requested state
400261 Unable to transition a direct deposit in reversed state
400262 Unable to transition a direct deposit in rejected state
400263 Unable to transition a direct deposit for an inactive cardholder
400264 Unable to reject a direct deposit 5 days after effective date
400265 Invalid direct deposit state detected
400267 Invalid cron expression
400268 Default cron expression not found

Funding Sources / Funding Addresses / Fees / Real Time Fee Groups/ Direct Deposit endpoints 404

Error Code Error Message
404150 User does not have any funding accounts
404151 Cardholder does not have any funding addresses
404152 Program account not found
404153 Points account not found
404154 Fee not found
404155 Funding account not found
404156 Real time fee group not found
404157 Deposit account not found
404158 Direct deposit not found
404159 Direct deposit transition not found
404160 Bulk issuance request not found
404161 Chargeback transition not found
404162 Program reserve account not found

Funding Sources / Funding Addresses / Fees / Real Time Fee Groups/ Direct Deposit endpoints 422

Error Code Error Message
422037 Cardholder not active
422038 Unable to reverse transaction for chargeback
422039 Unable to refund transaction for chargeback
422040 Unable to reverse provisional credit for chargeback
422041 Unable to grant provisional credit for chargeback
422042 Unable to create direct deposit
422043 Unable to create direct deposit transition
422044 Unable to map direct deposit state to internal transaction type

MCCGroups endpoints 400

Error Code Error Message
400375 Invalid MCC start
400376 Invalid MCC end
400377 Invalid MCC range
400378 Invalid MCC

MCCGroups endpoints 403

Error Code Error Message
403009 User is forbidden to modify this mcc group

MCCGroups endpoints 404

Error Code Error Message
404325 MCC group not found

Merchants / Stores endpoints 400

Error Code Error Message
400100 A merchant with the same token already exists
400101 A store with the same MID already exists
400102 A store with the same token already exists

Merchants / Stores endpoints 404

Error Code Error Message
404025 Merchant not found
404026 Store not found

MSA Orders / GPA Orders / Offer Orders / Offers endpoints 400

Error Code Error Message
400125 An offer with the same token already exists
400126 Purchase amount must be greater than 0
400127 Reward amount must not be less than 0
400128 Reward trigger amount must not be less than 0
400129 Reward trigger amount should not exceed purchase power
400130 Purchase amount must not exceed: amount
400131 Amount plus fees must be greater than 0
400132 Fees may not be empty
400133 GiftDescriptors must not exceed: amount

MSA Orders / GPA Orders / Offer Orders / Offers endpoints 404

Error Code Error Message
404050 Order not found
404051 GPA order token not found
404052 Offer not found

MSA Orders / GPA Orders / Offer Orders / Offers endpoints 422

Error Code Error Message
422025 Single load card cannot be re-loaded
422026 Insufficient funds to perform load from Program Reserve
422027 Unable to load funds for User that has not passed KYC

MSA Order Unloads / GPA Order Unloads / Offer Order Unloads endpoints 400

Error Code Error Message
400425 Unload amount is more than the load amount
400426 Cannot refund the points funding source
400427 Refund amount is less than or equal to ZERO
400428 Customer has no balance available
400429 The order token is not a valid GPA load token
400430 The order token is not a valid GPA unload token
400431 Unloads are not allowed for the given order
400432 Customer has no balance available in the campaign

MSA Order Unloads / GPA Order Unloads / Offer Order Unloads endpoints 404

Error Code Error Message
403008 User is forbidden from accessing this funding source

MSA Order Unloads / GPA Order Unloads / Offer Order Unloads endpoints 404

Error Code Error Message
404400 Return not found
404401 GPA unload order not found

MSA Order Unloads / GPA Order Unloads / Offer Order Unloads endpoints 412

Error Code Error Message
412010 Unload amount is more than the GPA balance

Network Transaction Types endpoints 400

Error Code Error Message
400725 Network tran type with the same network already exist

Network Transaction Types endpoints 404

Error Code Error Message
404550 Network tran type not found

Peer Transfers endpoints 400

Error Code Error Message
400250 Sender not found
400251 Recipient not found
400252 Unsupported Currency Code
400253 Sender User token and sender business token may not both be populated
400254 Recipient user token and recipient business token may not both be populated
400577 Business token was passed in user token field
400578 User token was passed in business token field
400579 Business tokens do not match
400581 Invalid active value

Peer Transfers endpoints 404

Error Code Error Message
404175 Transfer not found

Peer Transfers endpoints 422

Error Code Error Message
422050 Insufficient fund from sender account
422051 Sender and recipient must be active
422052 Cannot transfer funds on the same users

PINs / Control Tokens endpoints 400

Error Code Error Message
400275 Control token is invalid

PINs / Control Tokens endpoints 412

Error Code Error Message
412001 PIN is weak

Program Transfers endpoints 404

Error Code Error Message
404720 Program transfer type not found
404721 Program transfer not found

Program Transfers endpoints 412

Error Code Error Message
412722 Transfer amount is more than the GPA balance

Push to Card endpoints 400

Error Code Error Message
400580 Push To Card Provider not setup
400582 Invalid country code

Push to Card endpoints 404

Error Code Error Message
404180 Push to card information not found

Push to Card endpoints 422

Error Code Error Message
422130 Invalid Card Address 
422131 Invalid or Wrong CVV2
422132 Card not eligible for funding transfer
422133 Disbursement request declined
422134 Disbursement request declined due to insufficient fund
422135 Disbursement can not be processed since the card is still provisioning for service

Rewards endpoints 400

Error Code Error Message
400350 Excess from reward token is invalid
400351 One or more purchase tokens cannot be found or are still pending

Rewards endpoints 404

Error Code Error Message
404275 Reward program token not found or is not active
404276 Reward token not found

Rewards endpoints 409

Error Code Error Message
409075 Reward already redeemed

Simulate endpoints 400

Error Code Error Message
400325 Reversal cannot exceed the authorization amount
400326 Space not found

Simulate endpoints 404

Error Code Error Message
404250 Original transaction not found
404354 Retry can only be performed on a clearing transaction
404357 Transaction has already been cleared
404358 Retry can only be performed on a failed clearing transaction

Simulate endpoints 412

Error Code Error Message
412050 Unable to reverse transaction due to ITC
412051 Unable to reverse transaction due to state

Transactions endpoints 404

Error Code Error Message
404300 Transaction token not found

Users endpoints 400

Error Code Error Message
400050 A cardHolder with the same token already exists
400051 Parent not found
400052 Cardholder is not active
400053 Password mismatch
400054 Password has already been used
400055 Existing and new password cannot be the same
400056 Cardholder does not have an email
400057 User with the same email already exist
400058 Invalid birth date format received
400059 Invalid passport expiration date format received
400060 Invalid id card expiration date format received
400061 User token cannot start with reserved keyword
400062 Cardholder may not use a business parent's funding account
400063 Children of a User Cardholder may not have children
400064 The child of a User Cardholder that is the child of a Business must use parent account
400065 User with a User Child and a Business Parent must not use parent account
400066 Metadata key exceeded size limit of 255 characters
400067 Metadata value exceeded size limit of 255 characters
400068 Metadata key/value pair exceeded 20400074
400069 User with a User Child and a Business Parent  must not use parent account
400070 Updating user parent is not allowed as user uses parent account
400071 Uses parent account cannot be set to true without setting a parent card holder
400072 Uses parent account cannot be unset
400073 Invalid metadata key detected

Users endpoints 403

Error Code Error Message
403011 User is forbidden to update the active field
403012 User is forbidden to activate a user that was deactivated by a super user
403013 User is forbidden to activate a business that was deactivated by a super user
403014 User is forbidden to activate a card that was deactivated by a super user
403015 User is forbidden to activate a digital wallet token that was deactivated by a super user
403016 Override TSP error can only be set by admin user
403017 Override TSP error is only allowed for terminating tokens

User Transitions endpoints 400

Error Code Error Message
400750 Cannot transition user to ACTIVE until it has passed KYC
400752 Cannot transition user from UNVERIFIED to SUSPENDED
400754 Cannot transition user to LIMITED until it has passed KYC

User Transitions endpoints 404

Error Code Error Message
404531 User transition not found

Webhooks endpoints 400

Error Code Error Message
400600 Maximum active webhooks exceeded
400601 Event type is invalid
400602 Event token is invalid
400603 Event type not accepted
400604 Marqeta signature does not match
400605 Invalid webhook token

Webhooks endpoints 422

Error Code Error Message
422600 Webhook operation failed