# Code and Formats
source: https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md
## Error Response Handling {#error-response-handling}
The Consumer Clarity and Smart Subscriptions APIs support an array/list of requests and responses.
* The [HTTP response status codes](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#http-response-status-codes) provide information about the entire request/response as a whole.
* `ResultStatus` response objects provide information about the following:
* The [overall element](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#searchresults-response-objects) in the array (whether it's empty or not)
* [merchantResult](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#merchantresult-response-objects) (merchant found, not found, or invalid value in request)
* [purchaseReceipt](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#purchasereceipt-response-objects) (receipt available, not available, not accessible, or invalid value in request)
* [callCenterDetails](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#callcenterdetails-response-objects) (transaction too old or too new)
* [firstPartyTrustResult](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#firstpartytrustresult-response-objects) (missing value, multiple disputes, or evidence not found)
## HTTP Response Status Codes {#http-response-status-codes}
| Status code | Response | Description |
|-------------|--------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| 200 | OK | The request has succeeded and the response includes a payload. |
| 400 | BAD REQUEST | Applicable for any request errors, whether outside or inside the array/list. As soon as a request error is encountered within an individual element of the request array/list, this HTTP response status is returned with no response payload. See [400 Bad Request](https://developer.mastercard.com/consumer-clarity/documentation/code-and-formats/index.md#400-bad-request) for more information. |
| 401 | UNAUTHORIZED | Missing or invalid authentication token. |
| 403 | FORBIDDEN | The user is not authorized to perform the operation or the resource is unavailable for some reason, such as time constraints. |
| 404 | NOT FOUND | The requested resource could not be found. |
| 405 | METHOD NOT ALLOWED | The method specified in the Request-Line is not allowed for the resource identified by the Request-URI. POST is the only method allowed for this service. |
| 415 | UNSUPPORTED | The server does not support the request payload's media type. |
| 429 | TOO MANY REQUESTS | Too many requests hit the API too quickly. |
## Consumer Clarity API Specific Error Codes {#consumer-clarity-api-specific-error-codes}
### 400 Bad Request {#400-bad-request}
A 400 Bad Request Error indicates that we can't process your request, most likely due to an issue on your side. In these instances, we'll return an error code and message explaining the error.
This table shows the code and message you will receive and steps you can take to resolve the error.
| Reason Code | Description | How to resolve |
|--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------|
| `REQUEST_BODY_MISSING` | *if null or empty* Required request body is missing. | Provide a valid request body. |
| `REQUEST_BODY_MALFORMED` | Request body is malformed. Examples of dynamic description include: * *if just spaces* No content to map due to end-of-input. * *if extra comma* Unexpected character ('\]' (code 93)): expected a value. * *if just text* Unrecognized token 'text': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false'). | Provide a valid request body. |
| `UNSUPPORTED_CONTENT_TYPE` | Request `content-type` is not supported. | Provide a valid content type. |
| `SEARCH_CRITERIA_NULL` | searchCriteria must not be null. | Provide a valid searchCriteria request. |
| `SEARCH_CRITERIA_SIZE_INVALID` | searchCriteria must contain between 1 and 25 elements. | Provide a searchCriteria request that contains between 1 and 25 elements. |
| `LOCALE_MISSING` | locale must not be null or blank. | Provide a supported locale. |
| `LOCALE_UNSUPPORTED` | locale value does not match supported enumerations. | Provide a supported locale. |
## Response Result Status Object {#response-result-status-object}
The response objects provide additional information about each element in the array/list regarding successful (HTTP STATUS 200) responses. The following tables show details about response objects for `searchResults`, `merchantResult`, `purchaseReceipt`, `callCenterDetails`, and `firstPartyTrustResult`.
### searchResults response objects {#searchresults-response-objects}
| Scenario | ResultStatus Code | ResultStatus Message |
|-------------------------------------------|--------------------------------|------------------------------------------------------------------------------------|
| `searchCriteria` element is not null. | `OK` | OK. |
| `searchCriteria` element is null. | `SEARCH_CRITERIA_ELEMENT_NULL` | searchCriteria element must not be null. |
| No Consumer Clarity services are enabled. | `OK` | Please contact your Integration Team or Account Manager to configure your service. |
### merchantResult response objects {#merchantresult-response-objects}
If multiple errors exist, then the **ResultStatus Message** contains content related to all errors, separated by a space.
| Scenario | ResultStatus Code | ResultStatus Message |
|-------------------------------------------------------------------------------------------------------------------------|---------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Merchant was identified and some response data provided. | `MERCHANT_FOUND` | Merchant results provided. |
| Merchant was not identified so no response data provided. | `MERCHANT_NOT_FOUND` | Merchant could not be identified; no merchant results available. |
| `merchantResult` is returned empty due to suppressed merchant details on a found merchant. | `MERCHANT_FOUND_BUT_DETAILS_NOT_ACCESSIBLE` | Merchant details service not configured for this account. |
| `merchantResult` is returned but with suppressed merchant details in the response. | `MERCHANT_FOUND_BUT_DETAILS_NOT_ACCESSIBLE` | Merchant details service not configured for this account. |
| `merchantCriteria` is null. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantCriteria must not be null. |
| `cardAcceptorName` is null (or value contains no non-space characters). | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorName must not be null and must contain at least one non-space character. |
| `merchantIdentifierValue` is null (or value contains no non-space characters) and `merchantIdentifierType` is not null. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantIdentifierValue must not be null and must contain at least one non-space character if merchantIdentifierType is not null. |
| `merchantIdentifierType` is null and `merchantIdentifierValue` is not null. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantIdentifierType must not be null if merchantIdentifierValue is not null. |
| `cardAcceptorRegionCode` contains non-alphabetic or non-numeric characters (or value contains no non-space characters). | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorRegionCode is invalid, it must contain alphabetic or numeric characters only and must contain at least two non-space characters. |
| `cardAcceptorCountryCode` contains non-alphabetic characters (or value contains no non-space characters). | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorCountryCode is invalid, it must contain alphabetic characters only and must contain at least two non-space characters. |
| `merchantCategoryCode` contains non-numeric characters. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantCategoryCode is invalid, it must contain numeric characters only. |
| `merchantIdentifierType` value does not match supported enumeration. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantIdentifierType is invalid, it must contain supported enumeration only. |
| `cardAcceptorName` value length is between 1 and 50. | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorName length must be between 1 and 50. |
| `cardAcceptorLocation` value length is greater than 50. | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorLocation maximum length must be less than or equal to 50. |
| `cardAcceptorRegionCode` value length is less than 2 or greater than 3. | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorRegionCode length must be equal to 2 or 3. |
| `cardAcceptorCountryCode` value length is less than 2 or greater than 3. | `INVALID_FIELD_VALUE` | Invalid value ``: cardAcceptorCountryCode length must be equal to 2 or 3. |
| `merchantCategoryCode` value length is not equal to 4. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantCategoryCode length must be equal to 4. |
| `merchantIdentifierValue` value length is greater than 50. | `INVALID_FIELD_VALUE` | Invalid value ``: merchantIdentifierValue maximum length must be less than or equal to 50. |
### purchaseReceipt response objects {#purchasereceipt-response-objects}
If multiple errors exist, then the **ResultStatus Message** contains content related to all errors, separated by a space.
| Scenario | ResultStatus Code | ResultStatus Message |
|----------------------------------------------------------------------------------------------------------------------------------|-------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| Purchase Receipt URL is available. | `RECEIPT_AVAILABLE` | Purchase Receipt available. |
| Purchase Receipt URL is not available. | `RECEIPT_NOT_AVAILABLE` | Purchase Receipt not available for this merchant. |
| Purchase Receipt URL is not accessible. | `RECEIPT_NOT_ACCESSIBLE` | Purchase receipt service not configured for this account. |
| Purchase Receipt URL is temporarily not accessible. | `RECEIPT_TEMPORARILY_NOT_AVAILABLE` | Purchase Receipt is temporarily unavailable due to technical reasons. Please try again later. |
| Transaction is being determined as too new. | `TRANSACTION_TOO_NEW` | The Purchase Receipt is not available because the transaction is too new. Please retry at a later time. |
| Transaction is being determined as too old. | `TRANSACTION_TOO_OLD` | The Purchase Receipt is not available because the transaction is older than expected. |
| `transactionCriteria ` is missing a field value required by the merchant to generate a Purchase Receipt. | `MISSING_FIELD_VALUE` | Purchase Receipt cannot be obtained due to missing transaction criteria. |
| `transactionIdentifierValue ` is null (or value contains no non-space characters) and `transactionIdentifierType` is not null. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionIdentifierValue must not be null and must contain at least one non-space character if transactionIdentifierType is not null. |
| `transactionIdentifierType ` is null and `transactionIdentifierValue` is not null. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionIdentifierType must not be null if transactionIdentifierValue is not null. |
| `transactionIdentifierType ` value does not match supported enumerations. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionIdentifierType must contain supported enumeration only. |
| `transactionIdentifierValue ` value length is greater than 50. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionIdentifierValue maximum length must be less than or equal to 50. |
| `acquirerReferenceNumber ` value length is not equal to 23. | `INVALID_FIELD_VALUE` | Invalid value ``: acquirerReferenceNumber length must be equal to 23. |
| `acquirerReferenceNumber ` contains non-numeric characters. | `INVALID_FIELD_VALUE` | Invalid value ``: acquirerReferenceNumber value must contain numeric characters only. |
| `transactionDateTime ` value is not in a supported ISO 8601 format. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionDateTime value must be in YYYY-MM-DDThh:mm:ss±hh:mm or YYYY-MM-DD ISO 8601 format. |
| `transactionDateTime ` value length is less than 10 or greater than 25. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionDateTime length must be between 10 and 25. |
| `transactionAmount.value ` is null (or value contains no non-space characters) and `transactionAmount.currencyCode` is not null. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionAmount.value must not be null and must contain at least two non-space characters if transactionAmount.currencyCode is not null. |
| `transactionAmount.currencyCode` is null (or value contains no non-space characters) and `transactionAmount.value` is not null. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionAmount.currencyCode must not be null and must contain at least three non-space characters if transactionAmount.value is not null. |
| `transactionAmount.value` and `transactionAmount.currencyCode` are null (or contain no non-space characters). | `INVALID_FIELD_VALUE` | Invalid values: transactionAmount.value and transactionAmount.currencyCode must not be null and must contain at least one non-space character. |
| `transactionAmount.value` value length is less than 2 or greater than 12. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionAmount.value length must be between 2 and 12. |
| `transactionAmount.value` value is not in a supported format. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionAmount.value must start with the major unit currency, followed by a decimal point period to denote separation of the fractional suffix, if applicable for the currency. |
| `transactionAmount.currencyCode` value length is not equal to 3. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionAmount.currencyCode length must be equal to 3. |
| `transactionAmount.currencyCode` value is not in a supported ISO 4217 format. | `INVALID_FIELD_VALUE` | Invalid value ``: transactionAmount.currencyCode value must be an active ISO 4217 alphabetic code. |
| `cardFirstSix ` value length is not equal to 6. | `INVALID_FIELD_VALUE` | Invalid value ``: cardFirstSix length must be equal to 6. |
| `cardFirstSix ` contains non-numeric characters. | `INVALID_FIELD_VALUE` | Invalid value ``: cardFirstSix value must contain numeric characters only. |
| `cardLastFour ` value length is not equal to 4. | `INVALID_FIELD_VALUE` | Invalid value ``: cardLastFour length must be equal to 4. |
| `cardLastFour ` contains non-numeric characters. | `INVALID_FIELD_VALUE` | Invalid value ``: cardLastFour value must contain numeric characters only. |
| `issuerAuthorizationCode ` value length is not equal to 6. | `INVALID_FIELD_VALUE` | Invalid value ``: issuerAuthorizationCode length must be equal to 6. |
| `issuerAuthorizationCode ` contains non-alphabetic, non-numeric, or non-space characters. | `INVALID_FIELD_VALUE` | Invalid value ``: issuerAuthorizationCode must contain alphabetic or numeric characters only, and no space characters. |
| `paymentType ` is null (or value contains no non-space characters). | `INVALID_FIELD_VALUE` | Invalid value ``: paymentType must not be null and must contain at least one non-space character. |
| `paymentType ` value does not match supported enumeration. | `INVALID_FIELD_VALUE` | Invalid value ``: paymentType must contain supported enumeration only. |
### callCenterDetails response objects {#callcenterdetails-response-objects}
If multiple errors exist, then the **ResultStatus Message** contains content related to all errors, separated by a space.
| Scenario | ResultStatus Code | ResultStatus Message |
|---------------------------------------------|-----------------------|---------------------------------------------------------------------------------------------------------|
| Transaction is being determined as too new. | `TRANSACTION_TOO_NEW` | Call Center Details are not available because the transaction is too new. Please retry at a later time. |
| Transaction is being determined as too old. | `TRANSACTION_TOO_OLD` | Call Center Details are not available because the transaction is older than expected. |
### firstPartyTrustResult response objects {#firstpartytrustresult-response-objects}
In addition to the `callCenterDetails` response object errors, you might also encounter the following errors, which are specific to the First-Party Trust program.
Remember, we can only accept one request at a time for First-Party Trust.
##### FirstPartyTrustScenarioWithoutARNAndDisputeCriteria {#firstpartytrustscenariowithoutarnanddisputecriteria}
| Scenario | ResultStatus Code | ResultStatus Message |
|--------------------------------------------------------------------------------------------------------|-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| The transaction was not able to be located because the necessary request parameters were not provided. | `MISSING_FIELD_VALUE` | We could not proceed with the request based on the provided request parameters. To proceed, please provide either the Acquirer Reference Number and Payment Type or the Dispute Criteria in the request. |
##### FirstPartyTrustScenarioWithARNOnlyMultipleFound {#firstpartytrustscenariowitharnonlymultiplefound}
| Scenario | ResultStatus Code | ResultStatus Message |
|-------------------------------------------------------------------------------------------|--------------------------------|----------------------------------------------------------------------------------------------------------------------|
| More than one transaction was identified with the transaction criteria that was provided. | `MULTIPLE_DISPUTES_IDENTIFIED` | To proceed, please provide either additional transaction criteria parameters or the Dispute Criteria in the request. |
##### FirstPartyTrustScenarioWithARNOnlyNotFound {#firstpartytrustscenariowitharnonlynotfound}
| Scenario | ResultStatus Code | ResultStatus Message |
|----------------------------------------------------------------------------------|----------------------------------------|---------------------------------------------------------------------------------------------|
| The ARN was provided, but we need additional criteria to locate the transaction. | `FIRST_PARTY_TRUST_EVIDENCE_NOT_FOUND` | The First-Party Trust evidence could not be found based on the provided request parameters. |
##### FirstPartyTrustScenarioWithDisputeCriteriaNotFound {#firstpartytrustscenariowithdisputecriterianotfound}
| Scenario | ResultStatus Code | ResultStatus Message |
|-----------------------------------------------------------------------------------------|----------------------------------------|---------------------------------------------------------------------------------------------|
| The Dispute ID was provided, but we need additional criteria to locate the transaction. | `FIRST_PARTY_TRUST_EVIDENCE_NOT_FOUND` | The First-Party Trust evidence could not be found based on the provided request parameters. |
## Smart Subscriptions API Specific Error Codes {#smart-subscriptions-api-specific-error-codes}
### 400 Bad Request {#400-bad-request-1}
This table shows the code and message you might receive for the Smart Subscriptions API and the steps you can take to resolve the error.
| Reason Code | Description | How to resolve |
|----------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------|
| `REQUEST_BODY_MISSING` | *if null or empty* Required request body is missing. | Provide a valid request body. |
| `BAD_REQUEST` | Issuer's `clientId` is not onboarded. | Provide a valid `clientId` that is onboarded. |
| `BAD_REQUEST` | Invalid request answer. Required answers missing. | Make sure that all question IDs have a corresponding answer when you submit an action. |
| `BAD_REQUEST` | *if null or empty* Required request header is missing. | Provide a valid request header. |
| `REQUEST_BODY_MALFORMED` | Request body is malformed. Examples of dynamic description include: * *if just spaces* No content to map due to end-of-input. * *if extra comma* Unexpected character ('\]' (code 93)): expected a value. * *if just text* Unrecognized token 'text': was expecting (JSON String, Number, Array, Object or token 'null', 'true' or 'false'). | Provide a valid request body. |
| `UNSUPPORTED_CONTENT_TYPE` | Request `content-type` is not supported. | Provide a valid content type. |
## Gateway errors {#gateway-errors}
For more information about 4xx/5xx response codes and possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/).