# REST Error Handling source: https://developer.mastercard.com/iccp/documentation/error_handling/resterror_codes/index.md ## Error Structure {#error-structure} ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` For a failed request, the In Control for Commercial Payments (ICCP) API returns these responses: ### HTTP response codes {#http-response-codes} | **HTTP status** | **Description** | |-----------------|-------------------------| | 400 | Invalid Request | | 401 | Authentication Required | | 403 | Not authorized | | 404 | Resource not found | | 500 | Internal Server Error | | 501 | Not Implemented | ## In Control for Commercial Payments reason codes {#in-control-for-commercial-payments-reason-codes} The error response codes are listed below, ordered by endpoint. The error 400 response codes are returned for the `POST /iccp-real-card-accounts` and `PUT /iccp-real-card-accounts/{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |--------------------------|-------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------| | field.required | Name on card is required | Provide the name on the card. | | length.short | Name on card is too short | Provide a valid string between 1-100 characters. | | length.long | Name on card is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | Name on Card pattern is invalid. | Provide a valid string that does not violate the pattern rule. | | field.required | Expiry date is required | Provide the expiry date. | | length.short | Expiry date is too short | Provide a valid string of 7 characters. | | length.long | Expiry date is too long | Provide a valid string of 7 characters. | | pattern.invalid | Expiry date pattern is invalid | Provide a valid string that does not violate the pattern rule. | | expiry.invalid | Expiry date must not be in the past | Provide a valid expiry date in the format of yyyy-MM that is not before the current date. | | field.required | Alias is required | Provide an alias. | | length.short | Alias is too short | Provide a valid string between 1-100 characters. | | length.long | Alias is too long. | Provide a valid string between 1-100 characters. | | pattern.invalid | Alias pattern is invalid | Provide a valid string that does not violate the pattern rule. | | duplicate.alias | Alias already in use. Add a different alias. | Provide a unique alias in the request. | | field.required | Account Number is required | Provide an account number/PAN. | | length.short | Account Number is too short | Provide a valid string between 16-19 characters. | | length.long | Account Number is too long | Provide a valid string between 16-19 characters. | | pattern.invalid | Account Number pattern is invalid | Provide a valid string that does not violate the pattern rule. | | pan.invalid | Account Number is invalid | Provide a valid account number/PAN | | duplicate.account.number | Account Number is already present. Duplicate Account Numbers are not allowed. | Provide a unique accountNumber | | length.short | First Name is too short | Provide a valid string between 1-100 characters. | | length.long | First Name is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | First Name pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Middle Initial is too short | Provide a valid 1 character string. | | length.long | Middle Initial is too long | Provide a valid 1 character string. | | pattern.invalid | Middle Initial pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Last Name is too short | Provide a valid string between 1-100 characters. | | length.long | Last Name is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | Last Name pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Address Line1 is too short | Provide a valid string between 1-100 characters. | | length.long | Address Line1 is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | Address Line1 pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Address Line2 is too short | Provide a valid string between 1-100 characters. | | length.long | Address Line2 is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | Address Line2 pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Address Line3 is too short | Provide a valid string between 1-100 characters. | | length.long | Address Line3 is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | Address Line3 pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | PO Box number is too short | Provide a valid string between 1-15 characters. | | length.long | PO Box number is too long | Provide a valid string between 1-15 characters. | | pattern.invalid | PO Box number pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | City name is too short | Provide a valid string between 1-40 characters.. | | length.long | City name is too long | Provide a valid string between 1-40 characters. | | pattern.invalid | City name pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Country Subdivision code is too short | Provide a valid string between 1-40 characters. | | length.long | Country Subdivision code is too long | Provide a valid string between 1-40 characters. | | pattern.invalid | Country Subdivision code pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Postal Code is too short | Provide a valid string between 1-15 characters. | | length.long | Postal Code is too long | Provide a valid string between 1-15 characters. | | pattern.invalid | Postal Code pattern is invalid | Provide a valid string that does not violate the pattern rule. | | length.short | Country Code is too short | Provide a valid string between 1-3 characters. | | length.long | Country Code is too long | Provide a valid string between 1-3 characters. | | pattern.invalid | Country Code pattern is invalid | Provide a valid string that does not violate the pattern rule. | | country.code.invalid | Country Code is not valid | Provide a valid country code. | | length.short | Building text is too short | Provide a valid string between 1-25 characters. | | length.long | Building text is too long | Provide a valid string between 1-25 characters. | | pattern.invalid | Building text pattern is invalid | Provide a valid string that does not violate the pattern rule. | The following 400 error response codes are returned for the `POST /iccp-real-card-accounts`, `POST /iccp-real-card-accounts/searches`, and `PUT /iccp-real-card-accounts/{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|------------------------------|----------------------------------------------------------------| | field.required | Corp GUID is required | Provide a valid corporate GUID. | | length.short | Corp GUID is too short | Provide a valid string between 1-100 characters. | | length.long | Corp GUID is too long | Provide a valid string between 1-100 characters. | | pattern.invalid | Corp GUID pattern is invalid | Provide a valid string that does not violate the pattern rule. | The following 400 error response codes are returned for the `POST /iccp-real-card-accounts/searches` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-------------------------------------------|---------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------| | corpGUID.or.corpID.required | Corp GUID or Corp ID must be populated in the request | Provide a valid corporate GUID or legacy identifier. | | corpGUID.and.corpId.not.allowed.together | Corp GUID and Corp ID cannot be used together | Provide a valid corporate GUID or legacy identifier | | field.empty | Account GUIDs is not populate | The number of Account GUIDs do not follow the requirement. To perform search, enter between 1 to 100 Account GUIDs. | | field.limit.exceeded | Maximum number of Account GUIDs exceeded | The number of Account GUIDs do not follow the requirement. To perform search, enter between 1 to 100 Account GUIDs. | | field.empty | RCN IDs is not populated | The number of RCN IDs do not follow the requirement. To perform search, enter between 1 to 100 RCN IDs. | | field.limit.exceeded | Maximum number of RCN IDs exceeded | The number of RCN IDs do not follow the requirement. To perform search, enter between 1 to 100 RCN IDs. | | acountGUID.and.rcnId.not.allowed.together | The request's Account GUID and RCN ID cannot be used together | Provide either account GUIDS or RCN IDs, but not both. | | field.empty | Aliases is not populated | The number of Alias do not follow the requirement. To perform search, enter between 1 to 100 Aliases. | | field.limit.exceeded | Maximum number of Aliases exceeded | The number of Alias do not follow the requirement. To perform search, enter between 1 to 100 Aliases. | | field.empty | Account Numbers is not populated | The number of Account Numbers do not follow the requirement. To perform search, enter between 1 to 100 Account Number. | | field.limit.exceeded | Maximum number of Account Numbers exceeded | The number of Account Numbers do not follow the requirement. To perform search, enter between 1 to 100 Account Number. | | offset.invalid.multiple | Offset should be multiple of limit | Provide a valid offset such that it is between 0-999 and is a multiple of the limit. | | value.invalid | Sorting can only be performed by : aliasTxt, createdDate, or lastModifiedDateTime | Provide one of the following properties to sort by: alias, corpGuid, createdDate, or lastUpdateDate. | | value.invalid | Sorting order is invalid. To perform sorting, either use asc for ascending or desc for descending order | Provide either asc for ascending or desc for descending order. | The following 400 error response codes are returned for the `POST /iccp-real-card-accounts` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |--------------------------|------------------------------------------------------------------------------|--------------------------------------------------| | duplicate.account.number | Account Number is already present. Duplicate Account Numbers are not allowed | Provide a PAN/Account Number that is not active. | The following 400 error response codes are returned for the `PUT /iccp-real-card-accounts/{account_guid}/status` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|-------------------------------------------------|---------------------------------------------| | rcn.status.invalid | Real Card status can only be INACTIVE or ACTIVE | Provide "ACTIVE" or "INACTIVE" as a status. | The following 400 error response codes are returned for the `PUT /iccp-real-card-accounts/{account_guid}` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |---------------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------------------------| | rcn.update.inactive.not.allowed | User cannot update Inactive real card details | Provide an accountGuid associated with an active and existing real card | | corpGUID.invalid | Invalid Corp GUID. Corp GUID must be the GUID of an Issuer or Corporate | Provide an owner GUID that is associated with the real card being updated. You cannot update the company that the card is associated with. | | duplicate.alias | Alias is already present. Duplicate Aliases are not allowed | Provide a unique alias if you wish to update the existing card's alias. Else, provide the existing alias in the request. | The following 400 error response codes are returned for the `POST /iccp-real-card-accounts`, `POST /iccp-real-card-accounts/searches`, `GET /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}/status`, and `DELETE /iccp-real-card-accounts{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|---------------------------|----------------------------------------------------------------| | corpGuid.invalid | Corp GUID is invalid | Provide a valid GUID that is associated to a corporate entity. | | corpGuid.invalid | Corporate GUID is invalid | Provide a valid corporate GUID. | The following 400 error response codes are returned for the `GET /iccp-real-card-accounts/{rcn_id}/iccp-rcn-mappings` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|--------------------------|-------------------------------------------------------------------| | pattern.invalid | RCN ID should be numeric | Provide a valid identifier for the real card you are looking for. | The following 400 error response codes are returned for the `POST /iccp-real-card-accounts/searches`, and `GET /entity/{{entityGuid}}/descendentDetails?entityType=C&offset=0&limit=25` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-------------------------|------------------------------------|--------------------------------------------------------------------------------------| | offset.invalid | Offset should be between 0 to 999 | Provide a valid offset value between 0 to 999. | | offset.invalid.multiple | Offset should be multiple of limit | Provide a valid offset such that it is between 0-999 and is a multiple of the limit. | | limit.invalid | Limit should be between 1 to 200 | Provide a valid limit value between 1 to 200. | The following 400 error response codes are returned for the `GET /entity/{{entityGuid}}/descendentDetails?entityType=C&offset=0&limit=25` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|---------------------------------|-----------------------------------------------------------------------------------------------------------------------| | field.required | Entity type is required | The entityType query parameter must be populated with C (company), I (issuer), G (corporate group), H (issuer group). | | value.invalid | Entity type provided is invalid | The entityType query parameter must be populated with C (company), I (issuer), G (corporate group), H (issuer group). | | pattern.invalid | Offset should be numeric | Provide a valid offset value between 0 to 999. | | pattern.invalid | Limit should be numeric | Provide a valid limit value between 0 to 999. | The following 401 error response codes are returned for the `POST /iccp-real-card-accounts`, `POST /iccp-real-card-accounts/searches`, `GET /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}/status`, and `DELETE /iccp-real-card-accounts{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|-----------------------------------|--------------------| | user.not.authorized | Unauthorized - Access Not Granted | | The following 403 error response codes are returned for the `POST /iccp-real-card-accounts`, `POST /iccp-real-card-accounts/searches`, `GET /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}/status`, and `DELETE /iccp-real-card-accounts{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|-----------------------------------|---------------------------------------------------------| | user.not.authorized | Unauthorized - Access Not Granted | Provide a valid corporate GUID that you have access to. | The following 404 error response codes are returned for the `POST /iccp-real-card-accounts/searches` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|--------------------------|------------------------------------------------------------------| | resource.not.found | Corp ID not found | Provide a company identifier that exists and you have access to. | The following 404 error response codes are returned for the `POST /iccp-real-card-accounts`, `POST /iccp-real-card-accounts/searches`, `GET /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}/status`, and `DELETE /iccp-real-card-accounts{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|--------------------------------|----------------------------------------------------------------------------------------| | resource.not.found | Corp GUID not found | Provide a valid GUID that is associated to a corporate entity. | | resource.not.found | Issuer Guid could not be found | Provide a valid GUID that is associated to a corporate entity and has a parent issuer. | The following 404 error response codes are returned for the `GET /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}/status`, and `DELETE /iccp-real-card-accounts/{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|----------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | resource.not.found | RCN details not found for given Account GUID | Provide a valid account GUID that is associated to an existing real card. Ensure that the real card belongs to the company that is associated with the owner GUID in the request. | The following 404 error response codes are returned for the `GET /iccp-real-card-accounts/{rcn_id}/iccp-rcn-mappings` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|----------------------------------------|-------------------------------------------------------------------| | resource.not.found | RCN details not found for given RCN ID | Provide a valid identifier for the real card you are looking for. | The following 404 error response codes are returned for the `GET /entity/{{entityGuid}}/descendentDetails?entityType=C&offset=0&limit=25` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|--------------------------|-----------------------------------------------------------| | resource.not.found | Entity GUID not found | Provide a valid GUID for the company you are looking for. | The following 500 error response codes are returned for the `PUT /iccp-real-card-accounts/{account_guid}` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|----------------------------------|---------------------------------------| | server.error | Real Card data upsert has failed | Wait some time and retry the request. | The following 500 error response codes are returned for the `POST /iccp-real-card-accounts` endpoint. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|--------------------------|---------------------------------------------------------------------| | server.error | | Contact your local administrator or whoever can contact Mastercard. | | server.error | | Contact your local administrator or whoever can contact Mastercard. | The following 500 error response codes are returned for the `POST /iccp-real-card-accounts`, `POST /iccp-real-card-accounts/searches`, `GET /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}`, `PUT /iccp-real-card-accounts/{account_guid}/status`, and `DELETE /iccp-real-card-accounts{account_guid}` endpoints. | **Error/Reason code** | **Response description** | **How to Resolve** | |-----------------------|--------------------------|---------------------------------------------------------------------| | server.error | | Contact your local administrator or whoever can contact Mastercard. |