# Codes and Formats source: https://developer.mastercard.com/places/documentation/codes-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 Places API, error codes can be returned by the Mastercard gateway, which verifies your request's signature and routes to the correct location. For more 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} The Places API uses the following structure for every error response. 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 field or component that generated the error. Gateway errors use `Gateway`; Places validation errors can name the affected input, such as `countryCode`. | | 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 whether retrying could change the outcome. For example, retrying a request with invalid input will not succeed. If the error is related to an unexpected service timeout, retrying the call could produce 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: The following error codes are specific to Places API services. For other errors, refer to [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 to the below table. | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | 400 | MISSING_REQUIRED_INPUT | countryCode is missing | The provided countryCode is null. Provide a valid country code. | | 400 | INVALID_INPUT_VALUE | countryCode must be 3 characters in length | The provided country code is not 3 characters. Resubmit with a 3-character country code. | | 400 | INVALID_INPUT_VALUE | Longitude must be between -180 and 180 | The provided longitude is outside the valid range. Resubmit with a longitude between -180 and 180. | | 400 | INVALID_INPUT_VALUE | Latitude must be between -90 and 90 | The provided latitude is outside the valid range. Resubmit with a latitude between -90 and 90. | | 400 | INVALID_INPUT_VALUE | Out of range for the radius distance. The maximum distance is 15 miles. | The provided radius is greater than 15 miles. Resubmit without a radius or with a radius less than or equal to 15 miles. | | 400 | INVALID_INPUT_VALUE | Valid address or latitude and longitude must be provided. | Either a latitude/longitude must be provided or a valid address. | | 400 | 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. | | 400 | ENTITY_NOT_FOUND | Record is not present for the given Location ID: xxxx | The Location ID being searched does not exist. Resubmit with a valid location ID. | | 400 | INVALID_REQUEST | Method argument type is invalid | The Location ID being used is not a valid numeric value. Resubmit with a valid location ID. | ## Codes associated with specific endpoints are listed below. {#codes-associated-with-specific-endpoints-are-listed-below} API Reference: `GET /places/{location_id}` Returns detailed information about merchants based on the provided location ID. | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------|-------------------------------------------------------|---------------------------------------------------------------------------------------------| | 400 | ENTITY_NOT_FOUND | Record is not present for the given Location ID: xxxx | The Location ID being searched does not exist. Resubmit with a valid location ID. | | 400 | INVALID_REQUEST | Method argument type is invalid | The Location ID being used is not a valid numeric value. Resubmit with a valid location ID. | API Reference: `POST /places/searches` Returns detailed information on merchants based on the provided query parameter | Status Code | Reason Code | Description | Tip to resolve | |-------------|------------------------|-------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------------------------------| | 400 | MISSING_REQUIRED_INPUT | countryCode is missing | The provided countryCode is null. Provide a valid country code. | | 400 | INVALID_INPUT_VALUE | countryCode must be 3 characters in length | The provided country code is not 3 characters. Resubmit with a 3-character country code. | | 400 | INVALID_INPUT_VALUE | Longitude must be between -180 and 180 | The provided longitude is outside the valid range. Resubmit with a longitude between -180 and 180. | | 400 | INVALID_INPUT_VALUE | Latitude must be between -90 and 90 | The provided latitude is outside the valid range. Resubmit with a latitude between -90 and 90. | | 400 | INVALID_INPUT_VALUE | Out of range for the radius distance. The maximum distance is 15 miles. | The provided radius is greater than 15 miles. Resubmit without a radius or with a radius less than or equal to 15 miles. | | 400 | INVALID_INPUT_VALUE | Valid address or latitude and longitude must be provided. | Either a latitude/longitude must be provided or a valid address. | | 400 | 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. |