API Response Errors

HTTP status codes do not always provide sufficient information about the cause of an error. For more detailed programmatic handling of errors, responses contain additional JSON fields that describe the error.

Error format

Whenever an API request results in an error, the response will contain both a high-level error class specified by the code and a human-readable summary in the message.

{"code":2,"message":"Request body contains unprocessable entity."}

Extended error format

In some cases there is extended information available for clients about why a request has failed. For example, failing to supply a value for a required field1 will result in the following error:

{"code":2,"message":"Invalid entity.
metadata.email may not be empty (was null)","errors":[{"error":"invalid_value","location":"metadata.email","message":"metadata.email may not be empty (was null)"}]}

List of API Error Codes

The table below shows the list of error codes that may be returned in an API error response.

CodeMessageDescription
-1Unknown ErrorAn unknown error occured processing the API request
1Malformed authorization. Is the authorization type missing?API Key is missing or malformed
2Invalid EntityError with the JSON object passed in the request body
3ForbiddenAPI Key used with request does not have one of the roles authorized to call the API endpoint
1032Account number is invalid or missingAn invalid number was provided when creating a card
1051Payment not foundThe payment id requested was not found
1068Merchant account not associated with a marketplaceAttempting to create a marketplace payment with a merchant that is not associated with the marketplace
1069A wallet account could not be foundUnable to find the wallet account referenced in a marketplace create payment request
1070Marketplace info is required to create marketplace paymentMarketplace info was not provided with a marketplace create payment request
1076Payment amount did not fall within merchant charge limitsThe payment amount was greater than the maximum allowed limit or below the minimum allowed limit
1077Payment amount is invalidPayment amount must be greater than zero
1078Payment currency not supportedAn invalid currency value was used when making a payment
1083Idempotency key already bound to other requestThe idempotency key used when making a request was used with another payment. Please retry with a different value
1084This item cannot be canceledA cancel or refund request cannot be canceled
1085This item cannot be refundedA cancel or refund request cannot be refunded
1086This payment was already canceledThis payment was already canceled
1087Total amount to be refunded exceeds payment amountTotal amount to be refunded exceeds payment amount
1088Invalid source accountAn invalid source account was specified in a payout or transfer request
1089The source account could not be foundUnable to find the source account specified in a payout or transfer request
1091Invalid wire routing numberCould not find a bank with that routing number when creating wire bank account
1092Invalid IBANInvalid IBAN used in request to create a wire bank account
1093Source account has insufficient fundsThe source account has insufficient funds for the payout or transfer amount
1094The billing last name cannot be emptyWhen creating a card or bank account the billing last name must be provided
1096Encryption key id could not be foundAn encryption key id must be provided if request includes encrypted data
1097Original payment is failedAttempting to cancel or refund a failed payment
1098Wire payment amount failedWire payment must be greater than the minimum amount
1099The merchantWalletId query parameter is missingThe merchantWalletId query parameter must be set in association with the walletId parameter to retrieve wallet settlements
1100Invalid fiat account typeThe fiat account is invalid for the attempted payout type (e.g. using a business account for a marketplace payout)
1101Invalid country formatAn invalid ISO 31660-2 country code was provided
1102IBAN country mismatchIBAN does not match the provided bank country code
1103IBAN requiredIBAN is required is this request
1104Additional bank details requiredThere are additional bank details required for this request; details of which are provided in the response
1105Additional billing details requiredThere are additional billing details required for this request; details of which are provided in the response
1106Invalid district formatInvalid district format, must be a 2 character value
1107Payout limit exceededPayout can't be accepted as it would exceed the given limit
1108Unsupported CountryCountry not supported for customer
1109Invalid bin rangeNo bin range found for the card
1110Invalid card numberCard number is invalid
1111Invalid issuer countryIssuer country is invalid
2003The recipient address already existsThe blockchain address has already been associated with the account
2004The address is not a verified withdrawal addressThe blockchain address must first be verified before it can be used as a destination in a transfer request
2005The address belongs to an unsupported blockchainThe blockchain type used as a transfer destination is not supported
2006Wallet type is not supportedThe wallet type specified when creating an end user wallet is not supported
2007Unsupported transferA transfer from the provided source to the provided destination is not supported

Did this page help you?