# Code and Formats source: https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md ## API Gateway Errors {#api-gateway-errors} Error codes can be returned by the Mastercard gateway, which verifies your request's signature and routes to the correct location. These errors returned by the API Gateway are standard across Mastercard services. For more details about Gateway errors, see the [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/gateway-error-codes/) page of the general Mastercard Developers Platform documentation. ## Server API Errors {#server-api-errors} When you make a server side API call to Mastercard Checkout Solutions and there is an error, then the API service call response contains an HTTP error status code (4xx, 5xx) and an `Error` object. Note: Refer to the [error codes returned for the MDES Token Connect API](https://developer.mastercard.com/mdes-token-connect/documentation/code-and-formats/). ### Error Format and Example {#error-format-and-example} * JSON ```JSON { "status": "", "reason": "", "message": "", "errordetail": [ { "reason": "", "sourceType": "", "message": "", "source": "" } ] } ``` * JSON ```JSON { "status": 400, "reason": "INVALID_ARGUMENT", "message": "Cannot process the request because it is malformed or has incorrect/missing fields or values.", "errordetail": [ { "reason": "CANNOT_BE_NULL", "sourceType": "BODY", "message": "must not be null", "source": "srcClientId" } ] } ``` ### Attributes {#attributes} | Name | Type | Description | |-----------------------------------------------------------------------------------------------------------------------------|--------|---------------------------------------------------------------| | [**reason**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-reason-codes) | String | Reason code for the error. | | [**status**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#http-status-codes) | Number | HTTP status codes | | [**message**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-message) | String | Error message to be displayed for integrator. | | [**errorDetail**](https://developer.mastercard.com/issuer-enrollment/documentation/code-and-formats/index.md#error-detail) | Object | Reference object containing relevant details about the error. | #### Error Reason Codes {#error-reason-codes} The following table contains standard error reason codes and its resolutions. | Reason Code | Description and Remedy | |-----------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | **INVALID_ARGUMENT** | Shows when a request is malformed or invalid, or a mandatory parameter is missing. Identify the invalid/missing/incorrect value, correct the same, and retry. | | **INVALID_STATE** | Some error happened due to validation failure that caused the error. In your front end application, you should either show a generic message, or retry the same request again (it might succeed). | | **NOT_FOUND** | The requested resource/business entity or batchID is not found. Check the submitted data, correct if required, and retry. | | **PERMISSION_DENIED** | Access is denied to the requested resource as client does not have sufficient permission or has been locked. Check and confirm if you have passed the correct data, retry after correcting. Otherwise, contact your Mastercard representative for support and permissions. | | **UNAVAILABLE** | The server is currently unavailable. Retry after sometime. | | **INTERNAL** | Mastercard internal server error. Try again later. | #### HTTP Status Codes {#http-status-codes} | Status | Detail | |-----------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 200 - OK | Request succeeded and processed ok. | | 202 - Accepted | Batch ID included in the response body. | | 400 - Bad Request | This may be returned for example when the `SRC-Correlation-Id` portion of the request body is either missing or incorrect. See the `error` object in the response body for details. | | 401 - Unauthorized | Although defined as a response in the specification, the Mastercard Checkout Solution implementation will not return 401 errors. You may however see a 401 response returned from the API Gateway, for example if there is a problem with the Oauth signature. | | 403 - Forbidden | This may be returned for example when the `SRC-Client-Id` portion of the request body is either missing or incorrect, or because the combination of `SRC-Correlation-Id` and `SRC-DSA-Id` is incorrect. See the `error` object in the response body for details. | | 404 - Not Found | This may be returned when a checkout transaction is not found. | | 500 - Internal Server Error | See the `error` object in the response body for details. | | 503 - Service Unavailable | The server is currently unavailable. Typically the server is not able to serve the request temporarily. Retry after some time. | #### Error Message {#error-message} The following table shows the examples of `reason` values and the respective `message` string, which gives further information about the error. This is returned as application layer errors. | Reason | Message | |-----------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | INVALID_ARGUMENT | "Cannot process the request because it is malformed or has incorrect/missing fields or values." Thrown if there is an issue with the request body schema validation failure like length checks failure, mandatory check failure, type check failure, cookie not present etc. | | INVALID_STATE | "Request cannot be executed due to the incorrect field value." Thrown if there is an issue with the business validation failure on the response body like value mismatch, code not valid, invalid value, etc. | | UNAUTHORIZED | "Required authentication information is either missing or not valid for the resource." Thrown if Authentication information is missing or invalid. E.g., JWT Token not present or incorrect for an API with required Authentication Header. | | PERMISSION_DENIED | "Access is denied to the requested resource. Client does not have sufficient permission or has been locked." Thrown if the request does not have sufficient authentication level to access a specified resource. e.g., missing client-ids in the request body. **Note: this can occur in two situations, with different error messages. See the sample errors section below.** | | INTERNAL | "Internal server error. Something went wrong while processing the error." | | UNAVAILABLE | "Service unavailable. Typically the server is not able to serve the request temporarily. Retry after some time." | | NOT FOUND | "Cannot process the request because it is malformed or has missing/incorrect fields or values." | | AMBIGUOUS_CONSUMER_IDENTITY | "The consumer identities provided resulted in a partial match for a profile, however either the Email or Phone does not match." | | ABORTED | "Concurrency conflict, such as read-modify-write conflict." | | ALREADY_EXISTS | "The resource that a client tried to create already exists." | | RESOURCE_EXHAUSTED | "Either out of resource quota or reaching rate limiting." | | CANCELLED | "Request cancelled by the client." NOT IMPLEMENTED. | | DATA_LOSS | "Unrecoverable data loss or data corruption." | | LOCKED | "Client does not have sufficient permission or has been locked." | | NOT_IMPLEMENTED | "API method not implemented by the server." NOT IMPLEMENTED. | | DEADLINE_EXCEEDED | "Request deadline exceeded. This will happen only if the caller sets a deadline that is shorter than the method's default deadline (i.e. requested deadline is not enough for the server to process the request and the request did not finish within the deadline." | | INVALID_CONFIGURATION | "Cannot process the request because it is malformed or has incorrect/missing fields or values." | #### Error Detail {#error-detail} The `errordetail` is an optional list that provides the details of the error. * `reason` - Identifies the specific type of error. The reason element is a string enum value and will be one of: | Reason | Description | |--------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | CANNOT_BE_NULL | The supplied value cannot be null. | | INVALID_VALUE | The type is correct but the supplied value is not supported. | | PAN_INELIGIBLE | PAN Ineligible. | | INVALID_FORMAT | The format is not correct. | | ALREADY_EXISTS | The entity already exists. | | NOT_FOUND | The supplied value is not found. | | ISSUER_DECLINED | Declined by Issuer. | | TOKENIZATION_INELIGIBLE | Tokenization is not available for this PAN. | | INVALID_PAN | This entity has an invalid PAN for the requested operation. | | CORRUPT_DATA | The data associated with this entity is corrupted. | | EXPIRED | Card expired. | | MULTIPLE_FOUND | Multiple accounts found. | | NO_RESPONSE_FROM_ISSUER | The Issuer did not respond to the network message in the allotted time. An asynchronous message will be sent. The Token Requestor should retry after the time specified in the retry-after header. | | INVALID_TOKEN_UNIQUE_REFERENCE | The token unique reference (TUR) could not be found. | | TOKEN_MIGRATION_NOT_ELIGIBLE | Token is not in a status eligible for migration. | | INVALID_TOKEN_REQUESTOR_ID | Client is not authorized to TRID or TUR belongs to a different TRID than the one requested. | | UNEXPECTED_ERROR | There was an unexpected error. | | SUSPENDED_CARD | The issuer suspends the card and the card cannot be used for transactions. | | ACCOUNT_RANGE_NOT_FOUND | Consumer account range is not found. |
* `sourceType` - The source of the request where the error takes place, or which has caused the error. The `sourceType` element is a string enum value and will be one of: | sourceType | Description | |------------|-----------------------------------------------| | BODY | Refers to the body of the request. | | HEADER | Refers to any headers set in the request. | | QUERY | Any parameters set in the query string. | | PATH | Any parameter set in the path of the service. | | METHOD | Refers to the request method. |
* `message` - Custom error message released by the application. * `source` - Specifies the reason/location of the parameter in the request, which generated the error.