# Code and Formats source: https://developer.mastercard.com/locations-merchants/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 Location Services 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 location-merchants-api, it means the error was generated somewhere other than Location Services APIs | | ReasonCode | A unique constant identifying the error case encountered during Location Services 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 | ## Services API Specific Errors {#services-api-specific-errors} Note: Following error codes are specific to Location Services 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 Location Services API error object : ```java { "Errors": { "Error": [ { "Source": "countryCode", "ReasonCode": "INVALID_INPUT_VALUE", "Description": "countryCode must be 3 characters in length", "Recoverable": true, "Details": "GBRa' is invalid" } ] } } ``` For a complete list of Location Services 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 | | MISSING_REQUIRED_INPUT | countryCode is missing | The provided countryCode is null, Please provide valid country code | | INVALID_INPUT_VALUE | countryCode must be 3 characters in length | Provided country code is not 3 characters. Resubmit with a 3 character country code | | INVALID_INPUT_VALUE | Longitude must be between -180 and 180 | Provided Longitude is not within a valid range. Resubmit with a longitude between -180 and 180 | | INVALID_INPUT_VALUE | Latitude must be between -90 and 90 | Provided Latitude is not within a valid range. Resubmit with a longitude between -90 and 90 | | INVALID_INPUT_VALUE | Out of range for the radius distance. The maximum distance is 15 miles. | The provided radius distance was greater than 15 miles. Resubmit without a radius distance or one less than 15 miles | | INVALID_INPUT_VALUE | Valid address or latitude and longitude must be provided. | Either a latitude/longitude must be provided or a valid address. | | INVALID_INPUT_VALUE | Invalid unit. The valid values are KM and MILE. | Resubmit without a unit specified. The default is 5 miles. Alternatively submit with KM or MILE as the unit. | | INVALID_INPUT_VALUE | Merchant Type is missing or invalid | The merchant type must be paypass, easysavings, cashback, or repower. Resubmit with one of these merchant types. | | INVALID_INPUT_VALUE | Invalid limit. The maximum limit is 100 | Resubmit with a valid limit. The maximum limit is 100. | | MISSING_LOCATION_ID | locationId is missing | The provided locationId is null, Please provide valid location Id. | | INVALID_LOCATION_ID | locationId does not exist | The provided locationId is invalid, Please provide a valid location Id. | | INVALID_LOCATION_ID_FORMAT | locationId must be a valid number | The provided locationId format is invalid, Please provide a valid numarical location Id. | | MISSING_PROBLEM_CODE | problemCode is missing | The provided problemCode is null, Please provide a valid problemCode. | | INVALID_PROBLEM_CODE | is not a valid problemCode | The provided problemCode is invalid, Please provide a valid problemCode. | | INVALID_MERCHANTS_PROBLEM_CODE | is not a valid Merchants api problemCode | The provided problemCode is invalid, Please provide a valid merchants problemCode. | | MISSING_REQUIRED_INPUT | merchant_name is missing or invalid. Please provide at least 2 characters. Alternatively, you can use 'ALL' to view all available merchant names. | The provided merchant_name is null, Please provide a valid merchant_name atleast 2 characters or ALL. | | MISSING_REQUIRED_INPUT | merchant_type is missing or invalid. Please use one of the following: 'PAYPASS', 'REPOWER', 'EASYSAVINGS', or 'CASHBACK' | The merchant type must be paypass, easysavings, cashback, or repower. Resubmit with one of these merchant types. |