# API Error Response Best Practice source: https://developer.mastercard.com/mastercard-send/documentation/implementation/error-best-practice/index.md This page provides some of the common Mastercard Send API error responses and suggested best practices. For more information on gateway errors, see [this page](https://developer.mastercard.com/platform/documentation/errors-and-troubleshooting/oauth1-and-mtls-error-codes/). | HTTP Response Code | Response Code / Description | Best Practices | |--------------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 400 | INVALID_INPUT_FORMAT / Invalid content-type header syntax | Verify the value of the Content-Type header that the client is sending. Compare to what is allowed by specification. | | 400 | INVALID_BODY_HASH / The provided oauth_body_hash does not match the SHA256 hash of the request payload | Check if SHA bits used for the body hash calculation match the number of bits used for creating the digital signature. Check for invalid characters and make sure hashing algorithm uses a plain SHA function. | | 400 | INVALID_BODY_HASH / The provided oauth_body_hash does not match the SHA1 hash of the request payload | Check if SHA bits used for the body hash calculation match the number of bits used for creating the digital signature. Check for invalid characters and make sure hashing algorithm uses a plain SHA function. | | 400 | INVALID_OAUTH_SIGNATURE_METHOD / Invalid oauth_signature_method: HMAC-SHA1 | Ensure one of the supported signature methods RSA-SHA256 or RSA-SHA512 is used. | | 400 | INVALID_OAUTH_SIGNATURE_METHOD / Invalid oauth_signature_method: \[PROVIDED_SIGNATURE_METHOD\] | Ensure one of the supported signature methods RSA-SHA256 or RSA-SHA512 is used. | | 400 | RESOURCE_ERROR / \[ONE OF THE FOLLOWING\]: * Duplicate value * Account not eligible * Card type is not supported for merchant * Invalid currency * Primary contact cannot be deleted * Updating a different type of URI is not allowed * Invalid Request * Operation not allowed * Multiple resources found * Country not supported for merchant | Correct the payload data depending on the error detail code in response message or contact [Digital Support](mailto:digital.support@mastercard.com) or [API Support](mailto:apisupport@mastercard.com). | | 400 | INVALID_OAUTH_CONSUMER_KEY / Consumer key parameter must be 97 characters long, split by an exclamation mark symbol | Verify the format of the oauth_consumer_key header parameter value and ensure that it conforms to the specification. The consumer key should be obtained from the Mastercard Developers project dashboard. | | 400 | Payload too large | Reduce the payload size in order to comply with the gateway enforced limit shown in the Description field. | | 400 | UNSUPPORTED_CONTENT_TYPE / The request Content-Type (\[PROVIDED_CONTENT_TYPE\]) is not supported for this service | Review the supported content types for this service and make adjustments to the value of the Content-Type header to make the request conform to the service specification. | | 400 | INVALID_OAUTH_SBS / Problem with signature base string | Generally, the Description field will provide information about what is missing and needs to be addressed. This should not happen when the official libraries are used. | | 400 | INVALID_CLIENT_ID / The provided clientId was not found | The value that defines whether the host requires Production or Sandbox keys must match the environment of the consumer key value used in the request. A Sandbox consumer key won't work with the Production hostname and vice versa. Verify the values against the one displayed on the Mastercard Developers project dashboard. | | 400 | DECLINE / \[ONE OF THE FOLLOWING\]: * Card declined * Fraud detected * Card expired * Per transaction maximum amount limit reached * Partner has exceeded the daily limit configured in the system * Transaction Limit is less than the minimum configured for the partner * Consumer has exceeded the monthly limit configured in the system * Partner has exceeded the cycle limit configured in the system | Correct the payload data depending on the error detail code in the response message or contact [Digital Support](mailto:digital.support@mastercard.com) or [API Support](mailto:apisupport@mastercard.com). | | 400 | RESOURCE_UNKNOWN / No default account is defined for the consumer, Record not found | Correct the payload data depending on the error detail code in the response message or contact [Digital Support](mailto:digital.support@mastercard.com) or [API Support](mailto:apisupport@mastercard.com). | | 401 | AUTHENTICATION_FAILED / OAuth signatures did not match | In this situation, the easiest thing is to set up a new signing key in the Mastercard Developers project and update both the private key file and the oauth_consumer_key value on the request to match. | | 401 | INVALID_CLIENT_ID / Project \[PROJECT_ID\] doesn't have access to the requested service | Verify that the Mastercard Developers project that corresponds to the consumer key on the request contains the service being requested. If this is a Production service, ensure that the Production access has been granted, as indicated by the status on the project dashboard. | | 403 | VOLUME_THRESHOLD_EXCEEDED / You have exceeded your allowed call quota | The error will specify what the maximum allowed number of max_calls per configured \. Ensure your call logic doesn't exceed the allowed quota, or contact [API Support](mailto:apisupport@mastercard.com) if the quota needs to be increased. | | 403 | OAUTH_NONCE_USED / Nonce was already used within the current time window | Ensure that the generator used to create nonce strings is providing enough randomness. | | 403 | INVALID_OAUTH_TIMESTAMP / Minimum allowed: \[TIMESTAMP\] | Ensure the client's server clock is correctly synchronized with the gateway server's clock. Ideally, all servers should be using public NTP pools to synchronize their time. | | 403 | INVALID_KEY / The signing certificate is not valid | The description will indicate what part of the certificate validation has failed. Renewing or creating a new key using the Mastercard Developers project dashboard will resolve this issue. | | 500 | SYSTEM_ERROR / An unexpected error has occurred with the service you have requested | Make a GET call for the latest status of the transaction before retrying with a backoff algorithm. If the issue persists, contact [API Support](mailto:apisupport@mastercard.com). | | 5XX | SERVER_ERROR_xxx | The response code in the range of 5XX will never contain the Mastercard Send API Errors structure in the response. It reflects a network infrastructure issue between the client and Mastercard Send. If you receive the same error response after 15 consecutive requests or for a period of 5 minutes, stop processing for 5 minutes and then restart processing. If the same issue persists, contact [Digital Support](mailto:digital.support@mastercard.com). | | 202 | UNKNOWN | In some situations, a transaction response can have an 'UNKNOWN' status: `"status": "UNKNOWN"`. When this happens, we recommend that you use a GET request on the transaction after a minute to retrieve the latest status. If the status is still 'UNKNOWN', follow the *Transaction Responses with an 'UNKNOWN' Status* guidance in the Mastercard Developers documentation for the API you are using. |