# Code and Formats source: https://developer.mastercard.com/places/documentation/codes-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 Places 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-intelligence-places, it means the error was generated somewhere other than Places API | | ReasonCode | A unique constant identifying the error case encountered during Places 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 | ## Places API Specific Errors {#places-api-specific-errors} Note: Following error codes are specific to Places 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 Places 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 Places 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. |