# Codes and Formats source: https://developer.mastercard.com/identity-insights-solutions/documentation/code-and-formats/index.md ## Error Handling {#error-handling} ### Identity Insights Solutions API Error Codes {#identity-insights-solutions-api-error-codes} The Identity Insights Solutions API uses the standard HTTP response codes for success and failure notifications. Besides status codes in the 2XX range, errors are further classified by 4XX errors resulting from user-provided information and 5XX errors representing issues related to internal processing within the Service hosting the API. The content below outlines the error structure, and those errors most likely to be encountered by developers when using the API. ### Error Structure {#error-structure} To ensure a consistent experience across all Mastercard APIs, the following structure is followed by the Identity Insights Solutions API for each error scenario that can occur: ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` The response body provides additional details on the error. The table below provides an overview of the information available in the body of the error response. | **Name** | **Type** | **Description** | |-------------|----------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | Errors | Object | The error response model used by all of the API endpoints. | | Error | Object | List of error objects | | Source | String | Where the error occurred | | ReasonCode | String | A code defining the error, for example: * VALIDATION_ERROR * UNAUTHORIZED_REQUEST * DECRYPT_PRIVATE_KEY_NOT_FOUND * TRANSIENT_System_Failure * Required Field Missing | | Description | String | A description for this specific occurrence of the ReasonCode | | Recoverable | Boolean | Whether or not retrying this request could result in a successful response | | Details | String | More details of this specific error. This is an optional field and is sometimes used to give a more comprehensive description of the error that has occurred when required. | ## Error Codes {#error-codes} There are two categories of Error Messages: * Gateway Errors -- Generally traceable to issues related to the project details / MTLS Key in the request or their treatment in the security layer of the API. * API Errors -- Generally traceable to issues related to the data in the request, or issues internal to the application ### Gateway Error Codes {#gateway-error-codes} These errors are returned by the Mastercard gateway during verification of the request's signature and routing to the requested resource. For further information about the other response codes returned by the gateway and their possible resolutions, see [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes/). ### API Error Codes {#api-error-codes} The `POST /insights` endpoint supports two workflow contexts: * `workflowId = 1` for Identity Insights for Transactions * `workflowId = 2` for Identity Insights Risk Score Use the table below to confirm whether the error applies to both `/insights` workflows, to `/datashares`, or to `POST /insights` only. | **Reason Code** | **Description** | **Recoverable** | **HTTP Error code** | **Resolution Steps** | **Additional Information** | |-------------------------------|-----------------------------------------------------------------------------------------|-----------------|---------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------| | VALIDATION_ERROR | Required Data Element Missing | false | 400 | Include the missing fields that are required for the request body. | Applicable for `POST /insights` and `POST /datashares`.This is the generic validation error returned when required request data is missing. | | Required Field Missing | workflowId | false | 400 | Include the `workflowId` field and set it to `1` for Identity Insights for Transactions or `2` for Identity Insights Risk Score. | Applicable for `POST /insights`.No workflow-specific difference in handling. | | VALIDATION_ERROR | Invalid Format | false | 400 | Include the proper format required for the request body. | Applicable for `POST /insights` and `POST /datashares`.This usually indicates the project is not configured for the requested use case. | | VALIDATION_ERROR | Unable to identify customer entity type. Please contact your Mastercard representative. | false | 403 | Contact your Mastercard representative to request your project be onboarded to the product being requested. | Applicable for `POST /insights` and `POST /datashares`.No workflow-specific difference in handling. | | DECRYPT_PRIVATE_KEY_NOT_FOUND | Encrypted PrivateKey configuration not found | false | 400 | Encrypted Private Key required to be configured. Refer to [Payload Encryption](/documentation/api-basics/## Payload Encryption) for details. | Applicable for `POST /insights` and `POST /datashares`.No workflow-specific difference in handling. | | UNAUTHORIZED_REQUEST | Unauthorized request | false | 401 | Possible resolutions include: * Verify the mTLS client certificate matches the project * Confirm the API is enabled on the project * Confirm Sandbox versus Production key set | Applicable for `POST /insights` and `POST /datashares`.No workflow-specific difference in handling. | | INTERNAL_SERVER_ERROR | An unexpected error occurred while processing the request. | true | 500 | Service unavailable. Wait for some time and try again. | Applicable for `POST /insights` and `POST /datashares`.This can occur during either workflow or data share request when the service fails to process the request. | | TRANSIENT_System_Failure | An unexpected error occurred while processing the request. | true | 503 | Service unavailable. Wait for some time and try again. | Applicable for `POST /insights` and `POST /datashares`.This can occur during either workflow or data share request when the service fails to process the request. |