# Codes and Formats source: https://developer.mastercard.com/consent-management/documentation/codes-and-formats/index.md ## Error Codes {#error-codes} ### Error Structure {#error-structure} Mastercard returns errors in the following structure: ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` ### Gateway Error Codes {#gateway-error-codes} In addition to service error codes, error codes can also be returned by Mastercard's gateway, which is used to verify your request's signature and route it to the correct location. You can find a list of the errors returned by our gateway, as well as resolutions to each, on the following page [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). ## HTTP Response Codes {#http-response-codes} ### Common HTTP Responses {#common-http-responses} | Code | Response | Description | Resolution Steps | |------|-----------------------|---------------------------------------------------------------|----------------------------------------------------------------| | 200 | OK | Request was processed successfully. | No action required. | | 400 | Bad Request | Request body or parameters are invalid. | Validate schema, required fields, and values. | | 401 | Unauthorized | OAuth signature or credentials are invalid. | Verify consumer key, signing key, timestamp, and signature. | | 403 | Forbidden | Caller is authenticated but not permitted for this operation. | Verify product entitlement and onboarding configuration. | | 404 | Not Found | Resource does not exist or is not visible to caller. | Verify reference IDs and ownership context. | | 500 | Internal Server Error | Unexpected service-side error. | Retry if appropriate and contact support with request details. | ### Create Consents {#create-consents} | Code | Reason Code | Description | Resolution Tips | |------|---------------------------------------|--------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------| | 400 | **decrypt.error** | Could not find private key for given fingerprint (Public key fingerprint is missing or incorrect) | Confirm the correct key pair and fingerprint are configured for the project. | | 400 | **missing.param** | Missing required parameter `paramName` | Include the required request field and retry. | | 400 | **null.value** | Pan must not be null | Send a valid PAN value in `cardDetails.pan`. | | 400 | **value.non.numeric** | Pan must be numeric | Ensure the PAN contains digits only. | | 400 | **value.less.than.minlength** | Pan too short (Minimum length of pan should be 16 digits) | Correct the PAN length to at least 16 digits. | | 400 | **value.greater.than.maxlength** | Pan too long (Maximum length of pan should be 19 digits) | Remove extra characters and resend a valid PAN. | | 400 | **invalid.card.expiry.month** | Invalid card expiry month | Use a month from 01 to 12. | | 400 | **invalid.card.expiry.year** | Invalid card expiry year | Use a valid four-digit expiry year. | | 400 | **invalid.card.expiry** | Invalid card expiry (For current year month should be greater than or equal to current month) | Update the card expiry to a valid future date. | | 400 | **invalid.consent** | Unknown/Invalid consent name provided in the request. | Use a supported consent name such as `notification`. | | 400 | **invalid.card.details** | Need expiry, PAN, CVC and cardholder name to perform requested authentication | Include `pan`, `expiryMonth`, `expiryYear`, `cvc`, and `cardholderName`. | | 400 | **card.not.supported** | Card is not supported(3DS). (The card issuer does not support 3D Secure authentication for this card.) | Use a card that supports 3DS or retry with a different card. | | 400 | **asi.failed** | ASI check failed with response code `ResponseCode`. | Validate the card details and use a supported card for the requested flow. | | 400 | **card.blocked** | Issuer has blocked this card | Use a different card or contact the issuing bank. | | 400 | **invalid.consent.details** | * Consent details must be a map of string-\>string * Could not convert details to json string | Send `details` as a JSON object of string keys and values. | | 400 | **missing.required.parameters** | Missing required parameter /parameters `required details` | Add all required consent detail fields for the selected consent type. | | 400 | **invalid.required.parameters.value** | Missing/blank required detail parameter `requiredParam` | Populate the required `details` values and resend. | | 400 | **invalid.consent.detail.value** | `Detail Name` invalid value | Correct the value for the consent detail and retry. | | 400 | **blocked.card** | Blocked card | Replace the card with one that is active and eligible. | | 400 | **card.in.blocked.ica** | Issuer not supported | Use a supported card or partner configuration. | | 400 | **card.type.blocked** | Card type not supported : `unsupported card type` | Use a supported card type for this API. | | 400 | **missing.account.range.configs** | There is no account range configurations | Confirm the project is configured for the required account range, or contact support if the range is not enabled. | | 400 | **pan.not.within.any.account.range** | PAN is not within any account range | Test with a card from a supported BIN or account range for this product. | | 400 | **duration.too.short** | Consent Duration Days must be \> 0 | Set `consentDurationDays` to a positive value. | | 400 | **duration.too.long** | Consent Duration Days too big | Use a duration within the supported limit for this API. | | 400 | **card.smart.data.enabled** | Cannot enroll smart data enabled card | Use a card that is not enrolled for smart data, or choose a different test card. | | 400 | **card.country.blocked** | Country not supported | Use a card from a supported issuing country for this API. | | 403 | **not.enabled** | Client is not enabled | Confirm the project is enabled for Consent Management \& Enrollment. | | 403 | **invalid.merchant** | Consent for this merchant is not allowed | Verify the merchant configuration and product setup. | | 403 | **card.disabled** | Card is disabled | Confirm the card status with the issuer or use a different card. | | 404 | **unknown.legal.doc** | Unknown legal document name | Use an approved legal document name from the product requirements. | | 404 | **unknown.user** | Unknown user | Confirm the user identifier or create the user first. | | 400 | **invalid.identity.type** | Invalid identity type: `identityType` | Use a supported identity type such as `EMAIL`, `PHONE`, or `DEVICE_ID`. | | 400 | **invalid.identity.value** | Identity value not provided | Include a valid value for the selected identity field. | | Code | Reason Code | Description | Resolution Tips | |------|------------------------|------------------------------------------|---------------------------------------------------------------------------------------------------| | 400 | **no.auth.session** | No auth session found for card Reference | Start a new authentication session with the correct `card_ref` before retrying. | | 400 | **invalid.auth.state** | Authentication state error | Confirm the consent flow has reached the correct authentication stage before sending the request. | | 400 | **invalid.status** | Invalid 3DS fingerprint status | Regenerate the SDK fingerprint values and retry the auth start step. | | Code | Reason Code | Description | Resolution Tips | |------|------------------------|------------------------------------------|-----------------------------------------------------------------------------------------------------------| | 400 | **no.auth.session** | No auth session found for card Reference | Complete the start-authentication call for the same `card_ref` before verifying. | | 400 | **invalid.auth.state** | Authentication state error | Ensure the authentication challenge has been completed and the response data is passed through correctly. | ### Manage Consents {#manage-consents} | Code | Reason Code | Description | Resolution Tips | |------|------------------|-------------------------------------------------------|------------------------------------------------------------------------------------------------| | 404 | **unknown.card** | Unknown card (Caller does not own this cardReference) | Confirm the correct `card_ref` is being used and that the card belongs to the current project. | | Code | Reason Code | Description | Resolution Tips | |------|------------------|-------------------------------------------------------|-----------------------------------------------------------------------------------------------------| | 404 | **unknown.card** | Unknown card (Caller does not own this cardReference) | Validate the `card_ref` and retry only after confirming the resource belongs to the current caller. | | Code | Reason Code | Description | Resolution Tips | |------|---------------------|---------------------------------------|---------------------------------------------------------------------------------------------| | 404 | **unknown.consent** | Unknown consent OR Invalid consent id | Check the correct `consent_id` for the specified `card_ref` and retry with a valid consent. | ### Bulk Consents {#bulk-consents} Note: These bulk endpoints are not available in Sandbox. The reason codes below apply to the production-only bulk card consent flows. | Code | Reason Code | Description | Resolution Tips | |------|---------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------| | 400 | **pan.not.in.permitted.ranges** | One or more cards are not in permitted ranges for bulk add | Confirm the cards are within the supported account ranges for your project. | | 400 | **invalid.cards.value** | Cards should not be null | Send a valid `cards` array with card payloads. | | 400 | **unknown.consent.name** | Unknown consent `consentName` | Use a supported consent name such as `notification`. | | 400 | **invalid.consent.details** | * Consent details must be a map of string-\>string * Could not convert details to json string | Format consent details as a JSON object with string keys and values. | | 400 | **missing.required.parameters** | Missing required parameter /parameters `required details` | Include each required consent detail for the selected consent type. | | 400 | **invalid.required.parameters.value** | Missing/blank required detail parameter `requiredParam` | Populate any blank required values before retrying. | | 400 | **invalid.consent.detail.value** | `Detail Name` invalid value | Correct the consent detail values to an accepted format. | | 400 | **blocked.card** | Blocked card | Replace the card with an active eligible card. | | 400 | **pan.non.numeric** | Invalid PAN (not numeric) | Ensure the PAN contains digits only. | | 400 | **invalid.pan** | PAN should not be null | Include a valid PAN value in each card payload. | | 400 | **missing.account.range.configs** | There is no account range configurations | Contact support to confirm account range configuration for the project. | | 400 | **pan.not.within.any.account.range** | PAN is not within any account range | Test with cards in a supported account range. | | 400 | **duration.too.short** | Consent Duration Days must be \> 0 | Set a positive `consentDurationDays` value. | | 400 | **duration.too.long** | Consent Duration Days too big | Use a valid duration within the allowed range. | | 400 | **invalid.consents.value** | Consents should not be null or empty | Include at least one valid consent in the request. | | 403 | **not.allowed** | Not set up for bulk add API (contact [transaction.notifications@mastercard.com](mailto:transaction.notifications@mastercard.com) to request access) | Request bulk access from the Consent Management \& Enrollment team. | | 403 | **invalid.merchant** | Consent for this merchant is not allowed | Confirm merchant configuration and API access. | | 403 | **card.disabled** | Card is disabled | Use an active card or confirm the card status with the issuer. | | Code | Reason Code | Description | Resolution Tips | |------|---------------------|-------------------|---------------------------------------------------------------------------------------------------------| | 404 | **unknown.consent** | Consent not found | Verify the `cardRefs` belong to active consents in the current project and retry with valid references. |