# Exception Management
source: https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md
This page provides guidance for detecting and responding to payment exception scenarios. Follow this guidance to avoid causing Mastercard Send and Receiving Institutions (RIs) to process duplicate Payment Transactions. The term ['Repeat Flag POST request'](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/repeat-flag/index.md) means an API request that duplicates the values from a previous transaction request (the 'original POST request') **and** conforms to the [Repeat Flag requirements](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/repeat-flag/index.md#repeat-flag-requirements).
This information is written for the participant whose client is interacting with the Mastercard Send APIs directly, which is typically the Originating Institution (OI).
> **At a Glance:**
>
> * For timeouts or server errors, wait 40 seconds, then resend as a Repeat Flag POST request.
> * When `status` is 'PENDING' or 'UNKNOWN', wait 40 seconds, then submit a GET request to get the latest status.
> * For bad format responses, contact Mastercard Support and log affected transaction requests.
> * Do not submit a new payment request for the same transaction.
## About Exception Scenarios {#about-exception-scenarios}
Payment exceptions arise when Mastercard systems or dependent downstream networks are unable to successfully complete a financial transaction or provide a definitive, timely, and accurate status of the submitted transaction. These scenarios typically indicate a breakdown in the end-to-end processing flow rather than a business-level decline.
Such exceptions can be triggered by a range of technical factors, including but not limited to network connectivity disruptions, partial or full system outages, timeouts due to increased processing latency, or failures in intermediary components involved in transaction routing and authorization.
The main exception scenarios are:
* [Issue between the client and Mastercard Send](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#issue-between-the-client-and-mastercard-send)
* [Issue between Mastercard Send and the RI](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#issue-between-mastercard-send-and-the-ri)
* [Bad format response](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#bad-format-response)
### Issue Between the client and Mastercard Send {#issue-between-the-client-and-mastercard-send}
In this scenario, an issue with your systems, Mastercard Send, or the systems/entities between them either prevents the transaction POST request reaching Mastercard Send or prevents the API response reaching you. You may not know if your transaction request was processed by Mastercard Send and was approved by the RI or not.
You may receive one of these responses:
| Response | Recommended action |
|---------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 408 Request Timeout (no response), 5XX Server Error/Internal Server Error | See [Procedure When Timeout or Server Error Response](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#procedure-when-timeout-or-server-error-response) |
| 502 Transaction Not Processed: The transaction request likely did not reach Mastercard Send | See [Procedure When Timeout or Server Error Response](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#procedure-when-timeout-or-server-error-response) |
### Issue Between Mastercard Send and the RI {#issue-between-mastercard-send-and-the-ri}
In this scenario, an issue with Mastercard Send, the RI's systems, or the network systems/entities between them either prevents the Payment Transaction reaching the RI or prevents the RI's response reaching Mastercard Send. This affects Mastercard Send determining the transaction status.
You may receive one of these responses:
| Response | Recommended action |
|------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 202 with `status` 'UNKNOWN': Transaction status not yet known | See [Procedure When Transaction Status 'UNKNOWN' or 'PENDING'](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#procedure-when-transaction-status-unknown-or-pending) |
| 408 Request Timeout (no response), 5XX Server Error/Internal Server Error | See [Procedure When Timeout or Server Error Response](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#procedure-when-timeout-or-server-error-response) |
| 201 with `status` 'DECLINED' or 402 DECLINE: Mastercard Send has declined the transaction request due to timeout | If a 402 response, use a GET call to retrieve more details. The response values indicate the decline reason and whether you can try a new request, see [Retrying a Declined Transaction](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/declined-txn/index.md). |
### Bad Format Response {#bad-format-response}
In rare situations, such as a system glitch, you may receive an improperly formatted API response that does not have the typical response fields or error fields. You will not know if your transaction request was processed by Mastercard Send and was approved by the RI or not. For recommended action, see [Procedure When Bad Format Response](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#procedure-when-bad-format-response).
## Procedures {#procedures}
### Procedure When Timeout or Server Error Response {#procedure-when-timeout-or-server-error-response}
Follow this guidance when you receive a 408 Request Timeout (no response), 5XX Server Error/Internal Server Error, or 502 Transaction Not Processed. As shown in the sequence diagram below:
1. Wait 40 seconds after the original POST request.
2. Submit a Repeat Flag POST request that meets the [Repeat Flag requirements](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/repeat-flag/index.md#repeat-flag-requirements).
**NOTE:** It is important that this POST request is carefully coded to match the requirements. Do not send a duplicate transaction request on an alternate channel or payment system.
If Mastercard Send has previously seen and processed the transaction request, it returns a 201 response with the latest transaction status.
Otherwise, Mastercard Send returns a 201 response with `status` of 'PENDING', then sends a Payment Transaction message to the RI for approval.
If `status` is 'PENDING' or 'UNKNOWN'...
3. Wait 40 seconds after the PENDING/UNKNOWN response.
4. Submit a GET request with the Disbursement Reference ID from the POST request.
The 200 response will show the latest transaction status.
If the `status` is 'DECLINED', some of the response values indicate the decline reason and whether you can try a new request, see [Retrying a Declined Transaction](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/declined-txn/index.md).
If the `status` is still 'UNKNOWN' or 'PENDING', Mastercard Send will continually check the network for the latest status. Starting with a 40-second wait, use retry logic with exponential back‑off to resubmit the GET call until the status changes. If it is still 'UNKNOWN' or 'PENDING' 30 minutes after the original POST request, use the Transaction Research tool and/or the Mastercard Send daily reconciliation reports (after 24 hours) to check for the final status, see [Tools and Resources](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#tools-and-resources).
### Procedure When Transaction Status 'UNKNOWN' or 'PENDING' {#procedure-when-transaction-status-unknown-or-pending}
Follow this guidance when you receive a 202 Accepted with transaction status 'UNKNOWN'. You can also follow this guidance when a GET 200 response `status` is 'UNKNOWN' or 'PENDING', or when a Repeat Flag POST 201 response `status` is 'PENDING'. As shown in the sequence diagram below:
1. Wait 40 seconds after the response.
2. Submit a GET request with the Disbursement Reference ID from the POST request.
The 200 response will show the latest transaction status.
If the `status` is 'DECLINED', some of the response values indicate the decline reason and whether you can try a new POST request, see [Retrying a Declined Transaction](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/declined-txn/index.md).
If the `status` is still 'UNKNOWN' or 'PENDING', Mastercard Send will continually check the network for the latest status. Starting with a 40-second wait, use retry logic with exponential back‑off to resubmit the GET call until the status changes. If it is still 'UNKNOWN' or 'PENDING' 30 minutes after the original POST request, use the Transaction Research tool and/or the Mastercard Send daily reconciliation reports (after 24 hours) to check for the final status, see [Tools and Resources](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#tools-and-resources).
### Procedure When Bad Format Response {#procedure-when-bad-format-response}
Follow this guidance when you receive improperly formatted responses that do not have the typical response fields or error fields:
1. Contact Mastercard Support, providing a sample of the bad format response. Keep your Mastercard representative informed during this exception period.
2. Log all the transaction requests that receive bad format responses.
3. Once this exception situation is resolved and you receive correct API responses from Mastercard Send again, do the following for each transaction request that had a bad format response (those logged in the previous step):
a. Submit a GET request with the Disbursement Reference ID from the POST request.
Avoid sending a very large number of API requests in a short amount of time, or else you may exceed the API's rate limiter and receive a 429 Too Many Requests response.
If the transaction request is found, the 200 response will show the latest transaction status.
b. If the transaction request is not found, indicated by a 404 Not Found response, wait 40 seconds, then submit a Repeat Flag POST request that meets the [Repeat Flag requirements](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/repeat-flag/index.md#repeat-flag-requirements).
**NOTE:** It is important that this POST request is carefully coded to match the requirements. Do not send a duplicate transaction request on an alternate channel or payment system.
Mastercard Send returns a 201 response with the latest transaction status. If `status` is 'UNKNOWN' or 'PENDING', see [Procedure When Transaction Status 'UNKNOWN' or 'PENDING'](https://developer.mastercard.com/mastercard-send-disbursements/documentation/tutorials-and-guides/exception-management/index.md#procedure-when-transaction-status-unknown-or-pending).
## Tools and Resources {#tools-and-resources}
In addition to the exception management guidance provided above, the following Mastercard tools and services can help you resolve and manage exceptions.
| Tool / Service | Availability | Description | Benefits |
|------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------|
| Transaction Research | Near real time in *Mastercard Move: Send Customer Portal* on Mastercard Connect | This service is available to customer operations teams, enabling them to research transactions in near real time and see the latest status. For guidance, see [Customer Portal](https://developer.mastercard.com/mastercard-send/documentation/customer-site/). | Your Operations teams can validate the transaction status of exceptions. |
| Mastercard Send daily reconciliation reports, specifically the Reconciliation and MAT reports (v7) or the GRN and GMR reports (v8) | Batch process reports available the following day | This is a program service that supplies a reconciliation report of all successful and failed transactions and also the status of exceptions. For guidance, see [Reconciliation Reports](https://developer.mastercard.com/mastercard-send/documentation/reports/). The reports are available via file transfer and the [Customer Portal](https://developer.mastercard.com/mastercard-send/documentation/customer-site/). | You can validate the status of exception transactions the following day. |
| Mastercom / Dispute management system | Mastercom UI on Mastercard Connect or Mastercom API via Mastercard Developers | This service provides customers with the ability to process disputes for exception transactions that are claimed by consumers. For guidance, see the [*Exception Management Guide for Mastercom Users*](https://trc-techresource.mastercard.com/r/bundle/m_EMCOM_en-us/page/d/en-US) in the [Technical Resource Center](https://trc-techresource.mastercard.com/) on Mastercard Connect. | OIs can process individual transaction disputes and claims from consumers. |
## Best Practices {#best-practices}
* Use a unique Disbursement Reference ID for each new transaction request that is not a Repeat Flag POST request.
* In exception situations:
* Do not retry the same transaction request on an alternate channel or payment system.
* Manage consumer communications as needed based on use cases in real time to ensure the consumer does not retry the transaction on an alternate channel or payment system.
* Wait the recommended time, as per the guidance on this page, before sending GET requests or Repeat Flag POST requests.
* Log all transaction attempts for audit and troubleshooting.
* Check all approved and declined transactions (as reported by the API response) in the reconciliation reports to ensure the statuses match. It is possible for statuses to change, such as reversals for fraud disputes.
Exceptions must be reconciled and resolved at the earliest available instance. Failure to resolve exceptions and/or incorrectly sending duplicate transaction requests can result in:
* The RI receiving excess funds and/or crediting the receiving account too many times.
* You or your partner OI being out of funds and/or debiting the sending account (or funding account) too many times.