Response and Error Codes

HTTP status code summary (not limited to):

HIPS uses conventional HTTP response codes to indicate the success or failure of an API request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted, a charge failed, etc.), and codes in the 5xx range indicate an error with HIPS’s servers (these are rare).

Not all errors map cleanly onto HTTP response codes, however. When a request is valid but does not complete successfully (e.g., a card is declined), we return a 402 error code. To understand why a card is declined, refer to the list of codes in the documentation.

HTTP CodeSuccessfulMeaning
200YesYour request was successful
201YesCreated - Your request was created
202YesAccepted - Your request was accepted
400NoBad Request – Your request has invalid data. Check your parameters.
401NoUnauthorized – Your API key is wrong, see Authentication
402NoPayment Required - Card declined or no payments are made to an order
403NoForbidden – The requested data is restricted for your api key.
404NoNot Found – The requested data is not found.
406NoNot Acceptable – You requested a format that isn’t json
429NoToo Many Requests – Your code is pounding our servers, to protect us from evil loops we have a request limit. Should you discover that you need to raise your limit, please contact support.
5XXNoSomething went wrong on HIPS’s end. (These are rare.)
7XX¯\ (ツ)/¯Sometimes, when you do something really unexpectedly silly, you might end up with a 7XX error. In that case we refer to 7XX-rfc :)

Error types

Error TypeMeaning
api_connection_errorFailure to connect to HIPS’s API.
api_errorAPI errors cover any other type of problem (e.g., a temporary problem with HIPS’s servers) and are extremely uncommon.
authentication_errorFailure to properly authenticate yourself in the request.
card_errorCard errors are the most common type of error you should expect to handle. They result when the user enters a card that can’t be charged for some reason.
invalid_requestInvalid request errors arise when your request has invalid parameters.
rate_limitToo many requests hit the API too quickly.
restrictedYour api key or account is restricted, contact support.

Misc error codes

Error TypeMeaning
card_not_supportedThe payment source does not support this type of purchase
currency_not_supportedThe payment source does not support the specified currency.
do_not_honorThe payment has been declined for an unknown reason
fraudulentThe payment has been declined as it suspects to be fraudulent
insufficient_fundsThe payment source has insufficient funds to complete the purchase
customer_not_acceptedHIPS rejects the customer
customer_blacklistedHIPS rejects the customer
unpaid_billsHIPS rejects the customer
customer_not_18Customer is not 18 (required by law)
no_such_personRejected - No such person found
sca_step_up_requiredSCA Requirements Under the PSD2:
Issuers wants to step up authentication (PIN verification required). If possible re-submit the transaction with PIN, otherwise decline. Please include original_transaction_id.
sca_second_tap_requiredSCA Requirements Under the PSD2:
Issuers requests a second tap of the card using a zero CVM limit. Please include original_transaction_id.

Decline reason codes

Error TypeMeaning
not_declinedThis is set if the transaction is approved
insufficient_fundsInsufficient funds or credit limit exceeded
declinedAuthorization declined by card issuer
no_3ds_authorizationSCA / 3D Secure required, but is aborted or not performed.
potential_fraudAnti fraud rejection
technical_errorTechnical error
merchant_setupSomething is not correct with the merchant setup. Normally the merchant is missing bank account.
timeoutTimeout
card_lostCard lost, retain card if possible
abandonedAuthorization expired (no capture after 7 days))
order_overpaymentPayment amount exceeds order amount
invalid_amountAmount format error
invalid_cardCard format error
invalid_test_cardTest card is required, please use a test card.
card_expiredCard is expired
credit_card_restrictedCredit Card is blocked by Merchant, please use a debit card.
restricted_cardCard type is blocked (normally country or BIN block)
invalid_cvvInvalid CVV2
non_eu_card_restrictedNon EU cards are blocked by Merchant
test_mode_requiredTest mode is required
merchant_balance_too_lowMerchant balance is to low to perform a refund. Please try again when merchant balance is higher.
shipping_validationShipping validation error
communication_errorCommunication error
unexpected_errorUnexpected error
incorrect_pinIncorrect PIN
duplicatedDuplicated transaction
invalid_transactionInvalid Transaction
merchant_not_on_fileMerchant setup error - contact support
no_referencing_transactionThe transaction type must be referencing a parent transaction.
not_permitted_to_terminalThe terminal is not allowing the transaction type
pin_entry_exceededPIN tries exceeded
exceeds_limitsLimits exceeded
rejected_by_userRejected by User
recurring_contract_inactiveThe recurring contract is inactive
recurring_contract_finalizedThe recurring contract is done
recurring_source_invalidThe source for the recurring contract is invalid
recurring_retries_exceededRecurring payment retries has exceeded limits, therefore the recurring contract is aborted
recurring_expiredThe source (normally card) for the recurring contract has expired.