Error codes

Learn how the Commerce API uses HTTP response status codes.

The Commerce API uses HTTP response status codes. These codes indicate whether an API request succeeded or failed. HTTP status codes group responses into the following classes:

  • The 2xx range indicates success.

  • The 4xx range indicates an error that failed based on the provided information provided (for example, you omitted a parameter or a charge failed).

  • The 5xx range indicates an error with Digital River's servers.

Some errors 4xx errors include an [error code](error-codes. The error code is a short string with a brief explanation.

Error format

Digital River uses the following format for errors:

"errors": {
"error": [
{
"relation": "https://api.digitalriver.com/v1/shoppers/SubmitCartResource",
"code": "{error-code}",
"subcode": "{error-subcode}",
"description": "{error-description}"
}
]
}

If it's a transaction error using a credit card saved in the payment source, the error may contain additional information as shown in the following declined message (declinedMessage) example:

"errors": {
"error": [
{
"relation": "https://developers.digitalriver.com/v1/shoppers/SubmitCartResource",
"code": "declined",
"subcode": "fraud_block",
"description": "The transaction has been identified by Digital River as fraudulent.",
"declinedMessage": {
"merchantDeclinedType": "Hard",
"customerDeclinedType": "Hard",
"code": "7011"
}
}
]
}

Declined messages

A declined message (declinedMessage) includes the following information:

Declined message

Description

code

This code helps to categorize failure reasons that look different but point to the same issue.

merchantDeclinedType

This field indicates the authentication decline type of transaction initiated by the merchant.

customerDeclinedType

This field indicates the authentication decline type of transaction initiated by the shopper.

Error codes

The following topics contain a list of API error codes.

400 Bad Request

400 Bad Request

Definition

dr_limited_token_invalid

The limited token is invalid, expired, or revoked. Provide a valid token and try again.

invalid-keyword-expression

Invalid keyword expression [expression entered]. Provide a valid keyword expression and try again.

invalid-request

Cannot validate the request for one of the following reasons:

  • A comment is missing. Provide the comment and try again.

  • Invalid page size. Must be positive, non-zero, and less than 100000.

  • Invalid payment method type for this request. Provide a valid payment method type and try again.

  • The Return object is missing. Provide the Return object and try again.

  • The return reason is missing. Provide the reason for the return and try again.

  • Line items to return are missing. Provide the line items to return and try again.

  • Line item quantity IDs are missing. Provide the line item quantity IDs and try again.

  • The specified quantity to return is invalid. The number must be greater than zero and less than or equal to the number of items eligible for return. Specify a valid quantity to return and try again.

  • The system cannot parse the request because the request is not valid. Provide a valid request and try again.

  • The line item ID is missing. Provide the line item DI and try again.

INVALID_RETURN_REASON

The Return reason is invalid. Provide a valid return reason and try again.

LINE_ITEM_CANNOT_BE_RESOLVED

Cannot resolve line item for the specified line item ID. Verify the specified line item ID is correct and try again.

LINE_ITEM_EXPIRATION_DATE_EXCEEDS

The line item exceeds the return window for the specified line item ID. The specified line item cannot be returned through the self-service Returns API.

LINE_ITEM_CANNOT_BE_RESOLVED

The line item had a problem while fetching the expiration date for the specified line item ID.

LINE_ITEM_HAS_LINE_LEVEL_ SATISFACTION_REFUND

The line item has a line item level satisfaction refund for the specified line item ID. The line item is not eligible for a self-service return.

LINE_ITEM_IS_LINKED_TO_SUBSCRIPTION

The line item is linked to a subscription. Cannot process the return for non-physical items.

LINE_ITEM_IS_NOT_PHYSICAL

The specified line item ID is not physical. Cannot process the return for items that are not physical.

LINE_ITEM_QTY_IDS_ARE_INVALID

The specified line item quantity IDs are not associated with the specified line item. Specify the correct line item quantity IDs for the specified line item and try again.

LINE_ITEM_QTY_IDS_MISSING_ FOR_PARTIAL_RETURN

The line item quantity IDs for this partial return are missing. Specify the line item quantity IDs to include in the specified partial return and try again.

LINE_ITEM_QTY_IDS_NOT_ELIGIBLE_ FOR_RETURN

Specified line item quantity IDs are not eligible for return for the specified line item ID. Verify the specified line item quantity IDS are correct and try again if they are not correct.

LINE_ITEM_QUANTITY_TO_RETURN_ IS_MORE_THAN_ALLOWED

The quantity of line items to return is greater than the expected return quantity for the specified line item ID. Specify a valid quantity of line items to return for the specified line item ID and try again.

NO_LINE_ITEM_PRESENT_IN_REQUISITION

The request contains no line items. The request must contain at least one line item. Include at least one line item in the request and try again.

NO_RETURN_REASON_CONFIGURED

Return reasons for the specified order ID are missing. Provide the reasons for the returns and try again.

NULL_RETURN_REQUEST

The return request cannot be null. Ensure the request is not null and try again.

ORDERID_CAN_NOT_BE_RESOLVED

Cannot resolve the specified order ID for the order. Provide a valid order ID for the order and try again.

PARTIAL_PRODUCT_COMBINATION_RETURN

The shopper wants to return part of a product combination. All components within the product combination must be returned. Return all line items associated with the product combination for specified requisition ID.

SITE_DOESNOT_ACCEPT_RETURN

The site does not accept returns. To enable returns for a site, contact your Digital River Representative.

REQUISITION_HAS_ORDER_LEVEL_ SATISFACTION_REFUND

The order has an order level satisfaction refund for a specified order ID. If an order has a satisfaction refund applied against it, the line items within that order are not eligible for return.

REQUISITION_NOT_ELIGIBLE_FOR_RETURN

The specified order ID is not eligible for return. The requisition is in a state that does not allow a return to occur

RETURN_PROCESSING_ERROR

An error occurred while processing the return for the specified order. Ensure the information is correct and try again.

RETURN_QUANTITY_CAN_NOT_LESS_THAN_ONE

Line item return quantity must be greater than 0 for the specified line item. Specify a number greater than zero and less than or equal to the number of eligible items for the line item return quantity and try again.

UNABLE_TO_RESOLVE_SITE

Cannot resolve the specified order ID for the order. Specify a valid site for the specified order ID.

validation-failure

Cannot validate the request for one of the following reasons:

  • The site does not accept the return.

  • The order is not in a returnable state.

  • The return window expired for the specified product.

  • The requested return quantity is greater than the eligible quantity for the line item.

  • Cannot return the specified line item through the self-service Returns API.

401 Unauthorized

401 Unauthorized

Description

invalid_client

The provided client is invalid. Provide the correct client information and try again.

invalid_request

The required parameter is missing or empty. Provide the missing parameter and try again.

invalid_token

Invalid token for the Shopper Session. The token is no longer valid and must be refreshed to continue making API calls. This error occurs when there is a bad Dispatch token or Global Commerce User API token. To resolve this error, issue an API call to identify where the token originated and when it expired, for example:

GET /oauth20/access-tokens?token=your_access_token HTTP/1.1 Host: api.digitalriver.com

Where your_access_token is a placeholder for the actual token.

The response shows you where the token originated in the domain field and when it expired in the expiresIn field.

403 Forbidden

403 Forbidden

Description

forbidden

Cannot complete the request, as the call is not permitted.

404 Not Found

404 Not Found

Description

resource-not-found

Could not find a [resourceName] resource with an internal ID [resourceId].

405 Method Not Allowed

405 Method Not Allowed

Description

method-not-allowed

OAuth API—Request used incorrect HTTP method. Shopper API—The method is not allowed.

409 Conflict

409 Conflict

Description

[resource]-already-exists

Tried to create a [resourceName] with an ID [resourceId], and that resource already exists.

account_closed

Stop all billing as this account is closed.

apply-payment-failure

Cannot apply a payment method to an empty cart or failed to apply the requested payment method to the cart.

apply-shopper-failure

Cannot apply the shopper account information to the cart.

card_expired

The card is expired.

card_limit_exceeded

The transaction exceeds the card limit amount.

card_type_block

The merchant has blocked this card type.

card_velocity_exceeded

The transaction exceeds the card velocity amount.

cart-fraud-failure

Cannot submit the order due to fraud validation failure.

cart-payment-failure

Cannot submit the order due to payment processing failure.

credit-card-declined

The credit card payment was declined.

credit-floor-exceeded

The total amount for the order does not exceed the credit card minimum.

credit-card-expired

The credit card used for payment has expired.

coupon-code-already-used

The shopper previously entered this coupon code. The shopper cannot use this coupon code again.

declined

The card has been declined for an unknown reason.

decline_do_not_retry

The card has been declined for an unknown reason.

do_not_honor

The card issuing bank has declined this payment.

EMPTY_LINE_ITEM_ID

The line item ID is missing. Provide the line item ID and try again.

EMPTY_LINE_ITEM_ID

The line order ID is missing. Provide the order ID and try again.

EMPTY_RETURN_REASON

The line return reason is missing. Provide the reason for the return and try again.

field-too-long

The field [fieldName] is longer than the maximum length [fieldMaxLength] allowed.

fraud

The transaction has been identified by the issuing bank as fraudulent.

fraud_block

The transaction has been identified by Digital River as fraudulent.

insufficient_funds

The card has insufficient funds to complete the purchase.

invalid_address

The address does not match the card network's records.

invalid_amount

The amount is not accepted by the card network.

invalid-bill-to-country

The country's billing or shipping address for the request is invalid.

invalid_card_bin

The card bin is invalid.

invalid_card_number

The card number entered is invalid.

invalid-coupon

The coupon code is invalid. The shopper cannot use the coupon code.

invalid-credit-card-expiration-date

The credit card expiration date specified for the cart is invalid.

invalid-credit-card-number

The credit card number specified for the cart is invalid.

invalid_currency

This currency is not supported.

invalid-currency-code

The requested currency is not supported.

invalid_expiration_date

The card is expired or the expiration date is invalid.

invalid-keyword-expression

Invalid keyword expression: [expression entered]

invalid-locale

The requested locale is not valid.

invalid-offer-id

The offer ID for the request is invalid.

invalid-payment-failure

Cannot process the cart because the payment methods were not set.

invalid-payment-method

The cart does not support the specified payment method.

invalid_pin

The PIN provided is invalid or incorrect.

invalid-request

Request missing required product identifier.

invalid_security_code

The security code provided is invalid or incorrect.

invalid-ship-to-country

Shipping Address country is restricted for request.

invalid-token

The request contains an invalid token.

invalid_transaction_type

The transaction type is invalid.

inventory-unavailable-error

Inventory unavailable for the product specified in the request.

ip-address-restriction-error

The country associated with the IP address for the request is restricted.

inventory-status-failure

Inventory unavailable for one or more of the products in the cart.

issuer_invalid_card

The card does not exist with the issuer.

issuer_not_found

The card issuer does not exist.

issuer_unavailable

The card issuing bank could not be reached.

limit_exceeded

The transaction amount exceeds your assigned limit.

line-item-creation-failure

Cannot create line-item for the specified product.

line-item-update-failure

Cannot update the line item for the request.

lost_stolen_card

The issuing bank has marked this card lost or stolen.

mid_limit_exceeded

The transaction amount exceeds the limit assigned for this MID.

no_response

The payment processor did not respond.

offer-already-used

The offer is already in use.

offer-not-active

The offer for the request is not active.

offer-not-applicable

Cannot apply the offer ID for the request to the cart.

offer-not-deployed

Cannot use an undeployed coupon code.

offer-not-deployed

Cannot use an undeployed coupon code.

offer-unavailable

The offer ID for the request is not available for the cart.

offer-usage-limit-exceeded

Exceeded the offer usage limit. Shoppers cannot use the coupon code.

operation-failed

Cannot complete the operation.

over-private-store-shopper-restriction

Cannot add the product to the cart. The shopper requested more than the maximum purchasable quantity [x], or the remaining purchasable quantity [y] is less than the quantity they requested.

payment-post-auth-failure

The order could not be submitted due to payment processing failure.

paypal-failure

Cannot process the cart because PayPal returned a failure or declined status.

paypal-lookup-failure

Cannot process the cart due to PayPal lookup processing failure.

pin_try_exceeded

The bank's allowable number of PIN tries has been exceeded.

private-store-remaining-quantity-under-line-item-restriction

Cannot add the product to the cart. The shopper requested more than the Remaining purchasable quantity [x] or less than the Minimum purchasable quantity [y].

rate-limit-quota-exceeded

Exceeded the quota for the allowed number of API requests.

restricted-bill-to-country

The Billing Address country for the request is restricted.

restricted_card

The use of this card has been restricted by the card network.

restricted-ship-to-country

The Shipping Address country for the request is restricted.

shopper-usage-limit-exceeded

The shopper exceeded the offer usage limit. The shopper cannot use the coupon code.

stop_recurring

The cardholder has requested all recurring and/or installment charges be stopped.

submit-cart-failed

The cart is not complete, so the shopper could not submit the cart.

under-private-store-line-item-restriction

Minimum purchasable quantity[x]; Cannot add the product to the cart.

voice_authorization_required

Voice authorization is required by the issuer.

500 Internal Server Error

500 Internal Server Error

Description

system-error

An unexpected system error occurred.