# Code and Formats source: https://developer.mastercard.com/merchant-identifier/documentation/code-and-formats/index.md ## HTTP Response Codes/Reason Codes {#http-response-codesreason-codes} 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 CONTENT | 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 | CONFLICT | 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} Apart from the error codes returned by the Mastercard Merchant Identifier API, error codes can be returned by the Mastercard gateway, which verifies your request's signature and routes to the correct location. 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. | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|------------------------------------------------------------------------------|--------------------------------------------------------| | 400 | INVALID_CLIENT_ID | clientId must not be null. | Provided client is null, please provide valid ClientId | | 400 | TOO_MANY_MATCHES | The input is associated with many merchants; no unique merchant can be found | Repeat query with a more detailed merchant identifier | | 400 | DESCRIPTOR_TOO_SMALL | The search string does not contain enough characters. | Repeat query with a longer merchant identifier | | 400 | MISSING_REQUIRED_INPUT | merchant_descriptor is missing or invalid | Provide a merchant descriptor as input | ## Codes associated with specific endpoints are listed below. {#codes-associated-with-specific-endpoints-are-listed-below} API Reference: `POST /merchants/searches` Returns detailed information on merchants based on the provided input data | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|------------------------------------------------|----------------------------------------------------------| | 400 | INVALID_INPUT_VALUE | merchantName must be greater than 1 character | Resubmit with a merchant name greater than one character | | 400 | INVALID_INPUT_VALUE | input exceeds maximum length of 500 characters | Resubmit with a merchant name less than 500 characters | | 400 | MISSING_REQUIRED_INPUT | merchantName cannot be empty | Resubmit with a merchant name populated | API Reference: `GET /merchants` Returns merchant details for matched merchants given a merchant descriptor as input | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|------------------------------------------------------------------------------|--------------------------------------------------------| | 400 | INVALID_CLIENT_ID | clientId must not be null. | Provided client is null, please provide valid ClientId | | 400 | TOO_MANY_MATCHES | The input is associated with many merchants; no unique merchant can be found | Repeat query with a more detailed merchant identifier | | 400 | DESCRIPTOR_TOO_SMALL | The search string does not contain enough characters. | Repeat query with a longer merchant identifier | | 400 | MISSING_REQUIRED_INPUT | merchant_descriptor is missing or invalid | Provide a merchant descriptor as input | API Reference: `GET /merchants-by-card-acceptor-ids` Returns merchant details for matched merchants given a card acceptor id and optional country code. | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|-------------------------------------------------------------------------------------|---------------------------------------------------------------------------| | 400 | MISSING_REQUIRED_INPUT | card_acceptor_id is missing or invalid | The card_acceptor_id is mandatory. Resubmit with a valid card acceptor id | | 400 | TOO_MANY_MATCHES | card_acceptor_id is associated with many merchants; no unique merchant can be found | This can not be resolved | | 400 | INVALID_INPUT_VALUE | card_acceptor_id must be less than or equal to 15 characters | Resubmit with a card acceptor id less than 15 characters | API Reference: `GET /merchants-by-tax-ids` Returns a list merchants details for matched merchant given a tax id | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|--------------------------------------------|-------------------------------------------------------------------------| | 400 | MISSING_REQUIRED_INPUT | tax_id is missing or invalid | The tax_id field is mandatory. Resubmit with a valid tax id | | 400 | MISSING_REQUIRED_INPUT | country_code is missing or invalid | The country_code field is mandatory. Resubmit with a valid country code | | 400 | INVALID_INPUT_VALUE | country code must be equal to 3 characters | Resubmit with 3 character country code |