# Code and Formats source: https://developer.mastercard.com/presentment/documentation/code-and-formats/index.md ## HTTP status codes/reason codes {#http-status-codesreason-codes} Resource requests use HTTP response codes to provide a coarse-grain indication of the result of each request. The table lists the most common expected response codes for the supported HTTP methods. | HTTP response code | Error code | Description | Resolution steps | |--------------------|----------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | 200 | OK | The request was completed successfully. | No action needed - request processed successfully. | | 201 | CREATED | Successful creation occurred using a POST request. The Location header will contain a link to the newly created resource. | No action needed - resource created successfully. Check Location header for new resource URL. | | 400 | BAD REQUEST | General error when the request could not be fulfilled due to errors such as validation errors or missing required data. | Validate request parameters, check required fields, and ensure proper data formats before retrying. | | 400 | MULTIPLE_ACCOUNTS_FOUND | Multiple ARK values are associated with a single accountId. | Resolve duplicate account mappings and use an identifier that maps to exactly one account. | | 400 | ENCRYPTION_ERROR | `encryptedData` is blank in the request body. | Populate encryptedData for encrypted requests. | | 400 | ENCRYPTION_ERROR | The request body is not encrypted. | Encrypt the request body using the expected encryption mechanism before sending it. | | 400 | LUHN_CHECK_ERROR | Luhn check validation failed. | Correct the PAN or BAN so it passes Luhn validation. | | 400 | PAYMENT_SCHEME_MISSING | Payment scheme is not configured. | Configure the payment scheme for the relevant program or product before retrying. | | 400 | PAYMENT_SCHEME_ERROR | Payment scheme validation failed. | Send a supported payment scheme and confirm it matches the program configuration. | | 400 | LANGUAGE_CHECK_ERROR | The preferredLanguage value in the request is not valid. | Use a supported preferredLanguage or locale value in the expected format. | | 400 | INVALID_PROGRAM_IDENTIFIER | Send a valid Program identifier in the request. | Provide a valid configured program identifier. | | 400 | INVALID_PRODUCT_CODE | BankProductCode is not valid. | Use a valid BankProductCode supported by the target program. | | 400 | PROGRAM_CONFIG_ERROR | Program is not subscribed to enrollment service. | Subscribe or configure the program for enrollment service access. | | 400 | ENROLLMENT_FILTER_ERROR | Enrollment filter validations failed. | Adjust the request so it satisfies enrollment filter and business-rule criteria. | | 400 | INVALID_INPUT | Supported value for userIdType is BCN or CRK. | Set userIdType to BCN or CRK only. | | 400 | INVALID_INPUT | Supported value for accountIdType is BAN. | Set accountIdType to BAN. | | 400 | ACCOUNT_ALREADY_EXIST | Account already exists. | Do not create a duplicate account; use the update or retrieval flow instead. | | 400 | ACCOUNT_ALREADY_ENROLLED | Account is already enrolled. | Avoid duplicate enrollment and check current enrollment status before calling. | | 400 | INVALID_INPUT | Supported value for userIdType is BCN. | Set userIdType to BCN. | | 400 | INVALID_INPUT | Supported value for accountIdType is BAN. | Set accountIdType to BAN. | | 400 | USER_ALREADY_EXIST | User already exists. | Do not create a duplicate user; use the update or retrieval flow instead. | | 400 | INVALID_INPUT | Supported value for accountIdType is ARK. | Set accountIdType to ARK for account update operations. | | 400 | INACTIVE_ACCOUNT_STATUS | Previous account status is Inactive. | Reactivate the account or use an active account before attempting the operation. | | 400 | INVALID_INPUT | Supported value for userIdType is ARK or CRK. | Set userIdType to ARK or CRK. | | 400 | INVALID_INPUT | Supported value for userIdType is BAN, BCN, ARK or CRK. | Use one of the supported values: BAN, BCN, ARK, or CRK. | | 400 | INVALID_INPUT | CompanyIca cannot be null or empty. | Provide a non-blank CompanyIca. | | 400 | INVALID_INPUT | AccountId cannot be null or empty. | Provide a non-blank accountId. | | 400 | INVALID_INPUT | UserIdType cannot be null or empty. | Provide userIdType. | | 400 | INVALID_INPUT | AccountIdType cannot be null or empty. | Provide accountIdType. | | 400 | INVALID_INPUT | BankProductCode cannot be null or empty. | Provide a non-blank BankProductCode. | | 400 | INVALID_INPUT | BankProductCode maximum allowed size is 20. | Reduce BankProductCode to 20 characters or fewer. | | 400 | INVALID_INPUT | Account cannot be null or empty. | Include the required account object or value in the request. | | 400 | INVALID_INPUT | AccountId maximum allowed size is 30. | Limit accountId to 30 characters or fewer. | | 400 | INVALID_INPUT | The preferredLanguage size is 5. | Limit preferredLanguage to 5 characters. | | 400 | INVALID_INPUT | CompanyIca must be at least 4 digits. | Send a numeric CompanyIca with at least 4 digits. | | 400 | INVALID_INPUT | AccountReferenceCode maximum allowed size is 50. | Limit AccountReferenceCode to 50 characters or fewer. | | 400 | INVALID_INPUT | CompanyIca must be 4-8 digits. | Send a numeric CompanyIca between 4 and 8 digits. | | 400 | INVALID_INPUT | UserId cannot be null or empty. | Provide a non-blank userId. | | 400 | INVALID_INPUT | UserId maximum allowed size is 30. | Limit userId to 30 characters or fewer. | | 400 | ADDRESS_CONVERSION_FAILED | Address conversion failed. | Correct the address structure or values so the address can be mapped successfully. | | 400 | INVALID_INPUT | AddressLine1 maximum allowed size is 80. | Limit addressLine1 to 80 characters or fewer. | | 400 | INVALID_INPUT | AddressLine2 maximum allowed size is 80. | Limit addressLine2 to 80 characters or fewer. | | 400 | INVALID_INPUT | AddressLine3 maximum allowed size is 80. | Limit addressLine3 to 80 characters or fewer. | | 400 | INVALID_INPUT | Incorrect `offersAccountStatusCode`. The only allowed update status is GOOD_STANDING to INACTIVE. | Only send the valid status transition GOOD_STANDING to INACTIVE. | | 400 | INVALID_INPUT | The businessPhoneNumber maximum allowed size is 25. | Limit businessPhoneNumber to 25 characters or fewer. | | 400 | INVALID_INPUT | BAN must be between 16 and 19 digits. | Send a BAN with 16 to 19 digits only. | | 400 | INVALID_INPUT | BAN must be numeric. | Remove non-numeric characters from the BAN. | | 400 | INVALID_INPUT | The city maximum allowed size is 30. | Limit city to 30 characters or fewer. | | 400 | INVALID_INPUT | The CountryCode minimum allowed size is 2 and the maximum allowed size is 3. | Use a 2- or 3-character country code, typically ISO format. | | 400 | INVALID_INPUT | Email address should be a valid email address. | Provide a syntactically valid email address. | | 400 | INVALID_INPUT | Email address maximum allowed size is 120. | Limit the email address to 120 characters or fewer. | | 400 | INVALID_INPUT | ExternalAccountId maximum allowed size is 10. | Limit ExternalAccountId to 10 characters or fewer. | | 400 | INVALID_INPUT | First Name maximum allowed size is 25. | Limit the firstName value to 25 characters or fewer. | | 400 | INVALID_INPUT | Last Name maximum allowed size is 25. | Limit the lastName value to 25 characters or fewer. | | 400 | INVALID_INPUT | Mobile Phone Number maximum allowed size is 25. | Limit mobilePhoneNumber to 25 characters or fewer. | | 400 | INVALID_INPUT | Open Date should be in the format YYYY-MM-DD. | Send openDate in YYYY-MM-DD format. | | 400 | INVALID_INPUT | Open Date maximum allowed size is 10. | Ensure openDate fits the expected 10-character date format. | | 400 | INVALID_INPUT | Postal Code maximum allowed size is 14. | Limit postalCode to 14 characters or fewer. | | 400 | INVALID_INPUT | State Province Code minimum allowed size is 2 and the maximum allowed size is 3. | Use a 2- or 3-character state or province code. | | 400 | INVALID_INPUT | Platform Identifier cannot be null or empty. | Provide a non-blank platform identifier. | | 400 | INVALID_INPUT | Possible scenarios: - Invalid enrollment Type - Enrollment Type is Targeted and FiIds more than one - Enrollment Type is Online and FiIds are empty/null | Use a supported enrollment type; for Targeted send exactly one FiId; for Online send non-empty FiIds. | | 400 | INVALID_INPUT | The end date should be after the start date or null. | Set the endDate after the startDate or leave it null if allowed. | | 400 | INVALID_INPUT | Enrollment Type does not exist. | Use a supported enrollment type value. | | 400 | INVALID_INPUT | Gender Code does not exist. | Use a valid configured gender code. | | 400 | INVALID_INPUT | A ZIP Code is required when the source is Rewards Network. | Include a ZIP code when the source is Rewards Network. | | 400 | INVALID_INPUT | Financial Institution ID is required | Include the Financial Institution ID in the request. | | 400 | INVALID_INPUT | The end date should be greater than or equal to the current date | Set the endDate to today or a future date. | | 400 | INVALID_INPUT | controlGroupIndicator must be either Y or N. | Set controlGroupIndicator to Y or N only. | | 400 | INVALID_INPUT | customerSegmentId must be 4 of the characters and must be alphanumeric. | Send a 4-character alphanumeric customerSegmentId. | | 400 | INVALID_INPUT | lastFourCardDigits must be 4 digits. | Send exactly 4 numeric digits. | | 400 | INVALID_INPUT | selfEnrollmentSource must be 2 digits. | Send exactly 2 numeric digits for selfEnrollmentSource. | | 400 | INVALID_INPUT | Invalid gender code. Valid codes are: 0, 1, 2, and 9. | Use one of the supported gender codes: 0, 1, 2, or 9. | | 400 | PROGRAM_CONFIG_IDENTIFIERS_ERROR | Program config identifiers are configured incorrectly. | Fix the program configuration identifiers in the configuration source and redeploy or reload if needed. | | 400 | INVALID_INPUT | Program identifier could only contain letters, numbers `-` or `_`. | Use only letters, numbers, `-` or `_` in programIdentifier. | | 400 | INVALID_INPUT | Program identifier maximum allowed size is 18. | Limit programIdentifier to 18 characters or fewer. | | 400 | INVALID_INPUT | Program identifier is required. | Provide programIdentifier. | | 400 | INVALID_INPUT | Action code is required. | Provide actionCode. | | 400 | INVALID_INPUT | Invalid action code. | Use a supported action code recognized by the service. | | 400 | INVALID_INPUT | Old account cannot be null or empty. | Provide a non-blank old account value. | | 400 | INVALID_INPUT | New account cannot be null or empty. | Provide a non-blank new account value. | | 400 | INVALID_INPUT | New customer cannot be null or empty. | Provide a non-blank new customer value. | | 400 | PROGRAM_NOT_FOUND | Program not found for the given FID. | Use an FID that has a configured program, or add the missing mapping. | | 400 | FI_NAME_NOT_FOUND | X-fid not found. | Send a valid X-fid header value. | | 400 | INVALID_INPUT | `X-Public-Key-Fingerprint` header is required for encrypted requests. | Include the X-Public-Key-Fingerprint header on encrypted requests. | | 400 | INVALID_INPUT | `X-Public-Key-Fingerprint` value is incorrect and cannot be used for encryption. | Send the registered fingerprint that matches the encryption key pair. | | 400 | INVALID_INPUT | `X-Openapi-ClientId` header is missing. | Include the X-Openapi-ClientId header. | | 400 | ACCOUNT_OUTSIDE_OF_MTR_MARKET | Account is outside of MTR market. | Use an account within the supported MTR market or route it through the correct regional flow. | | 400 | INVALID_INPUT | Hash BAN cannot be null or empty. | Provide a non-blank hashed BAN value. | | 400 | BAN_REBATES_NOT_ALLOWED | BAN rebates are not allowed. | Do not use the BAN rebates flow for this scenario; switch to a supported identifier or path. | | 401 | UNAUTHORIZED | Missing or invalid authentication token. | Verify authentication credentials, refresh tokens if expired, and ensure proper authorization headers are included. | | 401 | INVALID_MEMBER_ICA | Financial institution ID is not valid. | Send a valid member or FI ICA that exists in the system. | | 401 | UNAUTHORIZED | Client Identity is unknown. | Authenticate with a recognized client identity and valid credentials or tokens. | | 403 | FORBIDDEN | The user is not authorized to perform the operation. | Contact the administrator to verify user permissions or use an account with appropriate access rights. | | 404 | NOT FOUND | The requested resource was not found. | Verify the resource URL/ID is correct and the resource exists. Check for typos in the endpoint path. | | 404 | ACCOUNT_NOT_FOUND | The accountId in the request is not valid. | Send a valid existing accountId with the correct accountIdType. | | 404 | USER_NOT_FOUND | The userId in the request is not valid. | Send a valid existing userId with the correct userIdType. | | 404 | ACCOUNT_NOT_FOUND_FOR_USER | Account not found for user. | Ensure the provided user is linked to the specified account. | | 404 | INVALID_INPUT | User location not found. | Provide valid location data or ensure the location exists upstream. | | 405 | METHOD NOT ALLOWED | The requested URL exists, but the requested HTTP method is not applicable. | Verify that you are using the correct HTTP method. | | 409 | MULTIPLE_USERS_FOUND | Multiple CRK values are associated with a single customerId. | Resolve duplicate user mappings and use a unique customer or user identifier. | | 409 | PAN_BLOCK_ERROR | Error occurred while doing PAN block for auto enrollment. | Check PAN-block integration, request data, and downstream service availability. | | 409 | INVALID_INPUT | User is already enrolled. | Avoid duplicate user enrollment and check status before retrying. | | 409 | ACCOUNT_KEYS_NOT_FOUND | Account keys not found. | Ensure account keys exist or are generated and can be retrieved for the account. | | 422 | INVALID_INPUT | Unexpected error code received from BMI service. | Review BMI request and response mapping, logs, and downstream behavior. | | 500 | DECRYPTION_ERROR | Failed to decrypt the request body. | Verify the payload encryption, key pair, and fingerprint/header values match the expected configuration. | ## Gateway error codes {#gateway-error-codes} For further information about the error message fields, 4xx/5xx response codes, and possible resolutions, refer to: OAuth 1.0a and mTLS Error Codes OAuth 2.0 Error Codes ## Error objects in OAuth 1.0a and OAuth 2.0 {#error-objects-in-oauth-10a-and-oauth-20} Application error message ```json { "Errors": { "Error": [ { "Source": "publisher-service", "ReasonCode": "USER_NOT_FOUND", "Description": "The userId in the request is not valid.", "Recoverable": false, "Details": "null" } ] } } ``` Error with API Gateway only, before reaching application ```json { "Errors": { "Error": [ { "Source": "Gateway", "ReasonCode": "DECLINED", "Description": "Unauthorized - Access Not Granted", "Recoverable": false, "Details": null } ] } } ``` Application error message ```json { "recoverable": false, "source": "publisher-service", "error_description": "The userId in the request is not valid.", "details": "null", "error": "USER_NOT_FOUND" } ``` Error with API Gateway only, before reaching application ```json { "error": "insufficient_scope", "error_description": "requested scope is not permitted" } ``` ```json { "error": "access_denied", "error_description": "access denied" } ``` ## Error structure {#error-structure} 4xx/5xx error response messages have one of the following formats (the `Error` array may contain multiple error items): Single Error : ```json { "Errors": { "Error": [ { "ReasonCode": "", "Source": "", "Description": "", "Details": "", "Recoverable": true/false } ] } } ``` Multiple Errors : ```json { "Errors": { "Error": [ { "ReasonCode": "", "Source": "", "Description": "", "Details": "", "Recoverable": true/false },{ "ReasonCode": "", "Source": "", "Description": "", "Details": "", "Recoverable": true/false } ] } } ``` | Field | Description | |-----------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **ReasonCode** | A unique constant identifying the error case encountered during transaction processing. For example, `INVALID_SIGNATURE` is used when the request signature does not match the expected one. | | **Source** | The application that generated this error. Every error message that is generated and returned by the gateway will have this field equal to `Gateway`. When the value of the source field is something else, it means that the error was generated elsewhere. | | **Description** | Short description of the `ReasonCode` field. | | **Details** | Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors. | | **Recoverable** | Indicates whether this error will always be returned for this request, or if retrying could change the outcome. For example, if the request contains an invalid signature, retrying will never result in a success. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response. | ## Offers for Publishers API-specific errors {#offers-for-publishers-api-specific-errors} Sample of Offers for Publishers API error object : ```json { "Errors": { "Error": [ { "ReasonCode": "400", "Source": "PCLO API", "Description": "FId is not provided or Value provided is invalid", "Details": "Bad Request", "Recoverable": true } ] } } ``` The Offers for Publishers API-specific error codes are as follows: | Reason Code | Description | Tip to resolve | |-----------------------|----------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_USER_TOKEN | Invalid User Token | The provided User Token is invalid. Please provide a valid User Token. | | INVALID_FID | Invalid FID | The provided FID is invalid. Please provide a valid Financial Institution Identifier (FID). | | INVALID_OFFER_ID | Invalid offer ID | The provided offer ID is invalid. Please provide a valid offer ID. | | INVALID_ACTIVATION_ID | Invalid offer activation ID | The provided offer activation ID is invalid. Please provide a valid offer activation ID. | | SC_ACTIVATION_FAILED | Offer activation failed. For example, the offer is already activated | Activation attempt for the offer failed. For example, if the offer is already activated, please activate an offer that is not yet activated. | | INVALID_FEEDBACK | Invalid feedback | The feedback provided is invalid. Please provide valid feedback. | | OFFER_UNAVAILABLE | Offer no longer available | The provided offer is no longer available or is invalid. Please request an available and valid offer. | | USERTOKEN_UNAVAILABLE | User Token is not available for the provided user. | Please make sure that the User Token is created and available for the user. | ## Activation response status codes {#activation-response-status-codes} The activation response status codes indicate that the activation request is either QUEUED, IN_PROGRESS, COMPLETED, or FAILED. ## Next steps {#next-steps} Proceed to the [Support](https://developer.mastercard.com/presentment/documentation/support/index.md) section to access frequently asked questions and access technical support.