# Code and Formats source: https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md ## Errors Overview {#errors-overview} Resource requests use HTTP response codes to provide a coarse-grain indication of the result of each request. The most common expected response codes for the supported HTTP methods are as follows: | Status Code | Response | Description | |-------------|-------------------|-----------------------------------------------------------------------------------------------------------------------------| | 200 | OK | Everything worked as expected. | | 201 | CREATED | A POST method successfully created a resource. | | 202 | ACCEPTED | The server accepted the request and will execute it later. | | 204 | NO CONTACT | The server successfully executed the method but returned no response body. | | 400 | BAD REQUEST | The request was unacceptable, often due to missing a required parameter. | | 401 | UNAUTHORIZED | A client with its clientId does not have access. | | 402 | REQUEST FAILED | The parameters were valid but the request failed. | | 403 | FORBIDDEN | The API key doesn't have permissions to perform the request. | | 404 | NOT FOUND | The requested resource doesn't exist. | | 405 | NOT ALLOWED | The server does not implement the requested HTTP method. | | 406 | NOT ACCEPTABLE | The server does not implement the media type that would be acceptable to the client. | | 408 | REQUEST TIMEOUT | The client did not produce a request within the time that the server was prepared to wait. | | 409 | NO CONTACT | The request conflicts with another request (perhaps due to using the same idempotent key). | | 415 | UNSUPPORTED | The server does not support the request payload's media type. | | 422 | UNPROCESSABLE | The API cannot complete the requested action, or the request action is semantically incorrect or fails business validation. | | 429 | TOO MANY REQUESTS | Too many requests hit the API too quickly. | ## Gateway Error Codes {#gateway-error-codes} For further information about 4xx response codes and possible resolutions, See [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes) ## Error Structure {#error-structure} To ensure a consistent experience across all Mastercard APIs, the following structure is being followed by Merchant Identifier APIs for every error scenario that can occur. Single Error : ```java { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` Multiple Errors : ```java { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" }, { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": true/false, "Details": "" } ] } } ``` | Field | Description | |-------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | 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 than merchant-identifier-api, it means the error was generated somewhere other than Merchant Identifier API | | ReasonCode | A unique constant identifying the error case encountered during Merchant Identifier API processing. For example, INVALID_INPUT_VALUE is used when an input value does not match the required format | | Description | Short description of the ReasonCode field | | Recoverable | Indicates whether this error will always be returned for this request, or retrying could change the outcome. For example, if the request contains an invalid input, 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 | | Details | Where appropriate, indicates detailed information about data received and calculated during request processing, to help the user with diagnosing errors | ## Merchant Identifier API Specific Errors {#merchant-identifier-api-specific-errors} Note: Following error codes are specific to Merchant Identifier API services. For any other errors, please refer [Gateway Error Codes](https://developer.mastercard.com/platform/documentation/security-and-authentication/gateway-error-codes) for possible resolutions, Sample of Merchant Identifier API error object : ```java { "Errors": { "Error": [ { "Source": "merchant_descriptor", "ReasonCode": "MISSING_REQUIRED_INPUT", "Description": "merchant_descriptor is missing or invalid", "Recoverable": true } ] } } ``` For a complete list of Merchant Identifier API specific error codes, refer below table. | Reason Code | Description | Tip to resolve | |------------------------|------------------------------------------------------------------------------|--------------------------------------------------------| | INVALID_CLIENT_ID | clientId must not be null. | Provided client is null, please provide valid ClientId | | TOO_MANY_MATCHES | The input is associated with many merchants; no unique merchant can be found | Repeat query with a more detailed merchant identifier | | DESCRIPTOR_TOO_SMALL | The search string does not contain enough characters. | Repeat query with a longer merchant identifier | | MISSING_REQUIRED_INPUT | merchant_descriptor is missing or invalid | Provide a merchant descriptor as input |