> For the complete documentation index, see [llms.txt](https://docs.saferpay.com/home/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/error-handling.md).

# Error Handling

While successful payment execution is of the utmost importance to Saferpay, technical difficulties and failed transactions are unavoidable. This chapter explains how Saferpay handles these cases and how to gather information about what went wrong.

## HTTP status != 200

An NOK response, or an HTTP status code other than 200 (OK), does not necessarily mean that the connection to Saferpay failed. Saferpay uses other status codes to indicate the error type and that an error occurred.

Alongside this code, Saferpay also returns a JSON message containing details of what happened. Always check the message body, not only the returned error code.

For a list of status codes and parameters, see the [Saferpay Specification](https://saferpay.github.io/jsonapi/#errorhandling).

### Failed payments and processor errors

Let's look at how to retrieve the error response returned by the processor after a failed payment attempt or other issue.

Behind the scenes, Saferpay communicates with a wide range of processors to process payments. In case of an error or failed payment, Saferpay passes the processor response to you so that you can identify the reason.

To retrieve this response, proceed as you would for a successful payment. For the [Payment Page](/home/integration-guide/licences-and-interfaces/payment-page.md) or [Transaction Interface](/home/integration-guide/licences-and-interfaces/transaction-interface.md), Saferpay redirects the payer to **`ReturnUrl.Url`** and calls **`Notification.FailNotifyUrl`**. Then execute [Payment Page Assert](/home/integration-guide/licences-and-interfaces/payment-page.md#4-paymentpage-assert) for Payment Page, or [Transaction Authorize](/home/integration-guide/licences-and-interfaces/transaction-interface.md#4-transaction-authorize) for Transaction Interface.

Some direct requests, such as [Recurring Payments](/home/integration-guide/licences-and-interfaces/transaction-interface/recurring-payments.md) and [Refunds](/home/integration-guide/licences-and-interfaces/transaction-interface/refunds.md), return the error response immediately because there is no redirect.

The shared information also depends on the processor and the cardholder's bank. Saferpay returns as much information as possible. In some cases, the bank does not share the exact reason for a failure. Only the cardholder can then ask their bank for details.

#### Example

An example of a rejected payment could look like this:

**HTTP status code:** `402 Payment Required`

```json5
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_DECLINED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "OnGYzfbtEMWMSAlMUh9rb8CdzSlA",
  "ProcessorName": "MasterCard Saferpay Test",
  "ProcessorResult": "05",
  "ProcessorMessage": "Authorization declined"
}
```

### Don't just retry

If a transaction fails, do not just retry the transaction.

{% hint style="danger" %}
An unauthorized retry can lead to additional charges.
{% endhint %}

Saferpay returns a recommended **`Behavior`** and **`ErrorName`** that indicate whether you can retry:

<table><thead><tr><th width="176">Behavior</th><th width="301.3333333333333">ErrorName</th><th>What to do</th></tr></thead><tbody><tr><td>RETRY</td><td>Not important/various</td><td>Your request was correct but could not be processed at this time. You can retry immediately.</td></tr><tr><td>RETRY_LATER</td><td>Not important/various</td><td><p>Your request was correct but could not be processed at this time.</p><p>The reason could be insufficient funds in the cardholder's bank account or technical issues on the bank side.</p><p>You can retry later. The exact time frame varies by reason. Waiting at least 24 hours is recommended.</p><p>Note that <strong>you may attempt the request only 10 times within 30 days.</strong></p></td></tr><tr><td>OTHER_MEANS</td><td>Not important/various</td><td>The payment cannot succeed with this payment method but may be possible with another.</td></tr><tr><td>DO_NOT_RETRY</td><td>various</td><td><p>Your request was not correct. Do not retry it; it will not work under the current conditions.<br><br>This error is specific to the situation. It means that, given the parameters and the current state, including the payer's solvency, this request will not work.<br>These parameters can change over time, especially the payer's solvency, so a new request may succeed.<br><br>The <strong><code>ErrorMessage</code></strong>, <strong><code>ErrorName</code></strong>, and <strong><code>ProcessorMessage</code></strong> may provide more information about the circumstances.</p><p><strong>Depending on the circumstances, you may retry up to 10 times within 30 days.</strong><br></p></td></tr><tr><td>DO_NOT_RETRY</td><td>UPDATE_CARD_INFORMATION</td><td>Your request was not correct. Do not retry it; it will not work.<br><br>However, the ErrorName indicates that the card details may be out of date and need updating, for example after receiving a new expiration date.</td></tr></tbody></table>

#### More about the meaning

These behaviors and error names specifically apply to the request itself and not necessarily to the payment itself.

As an example:

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "3DS_AUTHENTICATION_FAILED",
  "ErrorMessage": "3D-Secure authentication failed",
  "TransactionId": "b5zQ22b6r9zOtAnES2Uxb6KOY14b",
  "OrderId": "4"
}
```

This example indicates that [3D Secure](/home/integration-guide/general-information/3d-secure.md) authentication failed for this transaction. The behavior applies to this request, in this case [Payment Page Assert](/home/integration-guide/licences-and-interfaces/payment-page.md#4-paymentpage-assert) or [Transaction Authorize](/home/integration-guide/licences-and-interfaces/transaction-interface.md#4-transaction-authorize). These requests always yield this result, so retrying does not help.

However, this does not mean that you cannot reattempt the payment itself. In this example, 3D Secure authentication could fail because the cardholder made a mistake. Reattempting the payment could succeed if the cardholder corrects it.

## Retry behavior and polling

In some cases, retrying is appropriate, for example after a timeout. Consider the following:

1. The processing timeout is 100 seconds. Saferpay communicates with internal and external systems. External systems can substantially increase processing time. Wait 100 seconds before retrying a request.
2. **Do not use polling to continuously request information.** Saferpay prohibits polling. Violating this rule can lead to your account being blocked.
   * You may voluntarily execute requests to obtain transaction information. For example, if you have not received a notification, execute [Payment Page Assert](/home/integration-guide/licences-and-interfaces/payment-page.md#4-paymentpage-assert) to check for activity.
3. Although polling is forbidden, you may implement a retry mechanism. After retrying, wait before trying again to avoid longer-lasting issues. If you receive no response after 100 seconds, retry immediately. If that fails, wait one minute before retrying. If it fails again, wait one hour, and so on. This staggered retry mechanism balances response time and resource use.

### The RequestId and RetryIndicator

The **`RequestHeader.RequestId`** and **`RequestHeader.RetryIndicator`** are solely for debugging and indicating retries.

The **`RequestId`** identifies a single request, not the whole payment. The merchant system must generate it. Ensure it is unique for every request.

If your request fails with a **`Behavior`** of **`RETRY`** or **`RETRY_LATER`**, you may reattempt it with the same **`RequestId`**. Increase the **`RetryIndicator`** by one to indicate a retry of a previous failed attempt.

The maximum number of retries/value for **`RetryIndicator`** is 9.

## Common error messages and their meaning

Some error messages returned by Saferpay have a specific meaning and solution.

Here is a list of common error messages and how to resolve them:

#### **AUTHENTICATION\_FAILED - "Invalid credentials":**

In this case, your application could not authenticate with the Saferpay gateway. This can have one or more of the following causes:

* Your [CustomerId](/home/master/common-saferpay-terms-glossary.md#customerid) is incorrect.
* Your [API-User](/home/master/common-saferpay-terms-glossary.md#api-credentials-api-user-api-password) is incorrect.
* Your [API-Password](/home/master/common-saferpay-terms-glossary.md#api-credentials-api-user-api-password) is incorrect.
* You are running on the wrong environment, e.g. using a Live account on the test environment and vice versa.

Ensure all values match and are configured correctly.

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "AUTHENTICATION_FAILED",
  "ErrorMessage": "Unable to authenticate request",
  "ErrorDetail": [
    "Invalid credentials"
  ]
}
```

#### **TRANSACTION\_ABORTED**

The payer aborted this transaction by clicking the **Cancel** button.

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETR",
  "ErrorName": "TRANSACTION_ABORTED",
  "ErrorMessage": "Transaction aborted",
  "TransactionId": "zM9v9SAtlpY5SAYCM0KxbhKzp5Mb",
  "OrderId": "0"
}
```

#### 3DS\_AUTHENTICATION\_FAILED

This error occurs if [3D Secure authentication](/home/integration-guide/general-information/3d-secure.md) fails. Since 3D Secure is an anti-fraud measure, Saferpay does not attempt the transaction when authentication fails. A failure can indicate stolen card details or malicious intent.

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "3DS_AUTHENTICATION_FAILED",
  "ErrorMessage": "3D-Secure authentication failed",
  "TransactionId": "3fnEh0bnrStzUAWnCWYfAb5C8KCb",
  "PayerMessage": "Card holder information -> Failed",
  "OrderId": "2"
}
```

#### **NO\_CONTRACT:**

In this case, you are requesting a payment method that is not activated for your account, or a currency that is not configured. Check these settings in the Saferpay Backoffice under [**Settings > Terminals**](/home/interfaces/backoffice/settings.md#payment-means-terminals). If a setting is incorrect, contact your sales account manager.

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETR",
  "ErrorName": "NO_CONTRACT",
  "ErrorMessage": "No contract for the combination of terminal, means of payment/service provider and currency",
  "TransactionId": "bAvfOzbpIlI5rAzG74IEA0x3j47b",
  "ProcessorResult": "",
  "ProcessorMessage": ""
}
```

#### **TRANSACTION\_IN\_WRONG\_STATE:**

This means there are transaction-flow steps that you must complete before the current one, or that you are repeating steps already completed. For example, you might miss a redirect or authorize a transaction without providing the required payment means.

The previous step, such as an action by the payer after a redirect, may also still be in progress.

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_IN_WRONG_STATE",
  "ErrorMessage": "Invalid action"
}
```

#### **TRANSACTION\_ALREADY\_CAPTURED:**

This is a warning rather than an error. It indicates that the transaction has already been captured. Neither the transaction nor the capture failed. A transaction can only be captured once.

Please see this chapter about [the capture and its importance](/home/integration-guide/licences-and-interfaces/capture-and-daily-closing.md).

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current Spec-Version]",
    "RequestId": "[your request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_ALREADY_CAPTURED",
  "ErrorMessage": "Transaction already captured"
}
```

#### Missing permissions to perform PayPal transactions

As a third-party payment method, [PayPal needs special setup](/home/integration-guide/payment-methods/paypal.md#activation) so Saferpay has permission to perform actions on your PayPal account.

If PayPal is not set up correctly, you receive the following error response when attempting a PayPal payment:

```json
{
    "ResponseHeader": {
        "SpecVersion": "[CURRENT SPECVERSION]",
        "RequestId": "[YOUR REQUESTID]"
    },
    "Behavior": "DO_NOT_RETRY",
    "ErrorName": "TRANSACTION_DECLINED",
    "ErrorMessage": "Transaction declined by acquirer",
    "TransactionId": "[TransactionId]",
    "ErrorDetail":[
        "Check that PayPal was setup as described in the Saferpay integration guide for the PayPal payment method."
    ],
    "ProcessorName": "PayPal",
    "ProcessorResult": "invalid_request",
    "ProcessorMessage": "No permission to set target_client_id",
    "OrderId": "[YOUR ORDERID]"
}
```

#### Soft decline/Additional customer authentication required

This is a special rejection that applies only in the PSD2 area. It means the transaction must be secured with Strong Customer Authentication (SCA), most commonly through [3D Secure](/home/integration-guide/general-information/3d-secure.md).

The [PSD2 topic](/home/integration-guide/general-information/psd2.md) provides more detail.

```json
{ 
  "ResponseHeader": {
    "SpecVersion": "[current SpecVersion]",
    "RequestId": "[unique request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "PAYER_AUTHENTICATION_REQUIRED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "llOKnfAEW57QSAErGdIYbAtAQ1fb",
  "ProcessorResult": "1A",
  "ProcessorMessage": "Additional customer authentication required"
}
```

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current SpecVersion]",
    "RequestId": "[unique request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "PAYER_AUTHENTICATION_REQUIRED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "dOrvUAAWn16USAU8d08OA10A03SA",
  "ProcessorResult": "65",
  "ProcessorMessage": "Soft decline, SCA required"
}
```

#### General decline

The most common rejection during normal business is the "General decline," or code "05."

This code occurs when the cardholder's bank or processor does not provide the exact reason for the rejection. The cardholder can ask their bank for more information. If this does not help, you, as the merchant, can ask your account manager for more details.

```json
{
  "ResponseHeader": {
    "SpecVersion": "[current SpecVersion]",
    "RequestId": "[unique request id]"
  },
  "Behavior": "DO_NOT_RETRY",
  "ErrorName": "TRANSACTION_DECLINED",
  "ErrorMessage": "Transaction declined by acquirer",
  "TransactionId": "prYlfSAMbGSttA6h29WWA33p68GA",
  "ProcessorName": "MasterCard Saferpay Test",
  "ProcessorResult": "05",
  "ProcessorMessage": "Authorization declined",
  "OrderId": "1"
}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.saferpay.com/home/integration-guide/licences-and-interfaces/error-handling.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
