# Code and Formats source: https://developer.mastercard.com/track-search/documentation/code-and-formats/index.md ## HTTPS status codes {#https-status-codes} 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: | HTTP Response Code | Response Description | |----------------------------|---------------------------------------------------------------------------------------------------------------------------| | 200 (OK) | The request was completed successfully. | | 201 (CREATED) | Successful creation occurred using a POST request. The Location header will contain a link to the newly created resource. | | 204 (NO CONTENT) | Successful update occurred using a PUT request. | | 400 (BAD REQUEST) | General error when the request could not be fulfilled due to errors such as validation errors or missing required data. | | 401 (UNAUTHORIZED) | Missing or invalid authentication token. | | 403 (FORBIDDEN) | The user has insufficient permissions to a resource or action. | | 404 (NOT FOUND) | The requested resource was not found. | | 422 (UNPROCESSABLE ENTITY) | Resource already exists / Resource has been modified. | ## Gateway Error Codes {#gateway-error-codes} Apart from the error codes returned by the Track Search 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 the 4xx response codes returned by the gateway and their 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 followed by the Track Search API for each error scenario that can occur. **Single Error:** ```json { "Errors": { "Error": [ { "source": "", "recoverable": "e.g. true/false", "details": "One of the request parameters is invalid, try again with the correct request." } ] } } ``` **Multiple Errors:** ```json { "Errors": { "Error": [ { "Source": "", "ReasonCode": "", "Description": "", "Recoverable": "true/false", "Details": "" },{ "source": "", "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 set to `Gateway`. If the field value is `TRACKSEARCH_API`, then the error is generated by the Payment Initiation application. | | **ReasonCode** | A unique constant identifies the error case encountered when any Payment Initiation API is called. For example, `FORBIDDEN` is used when the user has insufficient permissions to a resource or action. | | **Description** | Description of the `ReasonCode` field provided with additional details. | | **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 request parameter, retrying will never result in success. However, if the error is related to some unexpected timeout with the service, retrying the call could result in a successful response. | | **Details** | Provide detailed error information wherever appropriate to help in resolving errors. | ## Initiate bulk search request error codes {#initiate-bulk-search-request-error-codes} The following error codes can be returned when processing a POST/bulk-searches API call. Fix the errors and resend the API request for the Search API to complete your request. | Code | Description | Tip to Resolve | |-----------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------------| | lookupRequired | Lookup is required | Submit the type of entity to search. | | searchRequestIdRequired | `searchRequestId` is required | Submit a unique `searchRequestId` per search entity. | | searchRequestIdNotUnique | `searchRequestId` must be unique within a request | Submit a unique `searchRequestId` per search entity. | | searchRequestIdInvalid | `searchRequestID` must be alphanumeric and the maximum allowed length is 64 | Submit a unique `searchRequestId` per search entity that is alphanumeric and has a maximum length of 64 characters. | | lookupInvalid | Lookup must be a valid entity type | Select either BUYERS or SUPPLIERS as the lookup. | | buyerLookupNotAuthorized | User not authorized to search for buyers | Select a lookup for which you are authorized to search, for example SUPPLIERS. | | supplierLookupNotAuthorized | User not authorized to search for suppliers | Select a lookup for which you are authorized to search, for example, BUYERS. | | numMatchesExceeded | The maximum number of matches is 5 | Select a `maximumMatches` from 1 to 5. | | confExceed | Minimum confidence must be less than 1 | Select a `minimumConfidenceThreshold` less than or equal to 1. | ## Get results error codes {#get-results-error-codes} The following error codes can be returned when you retrieve results using the GET/{bulk_search_id}/results endpoint. These error codes are returned per searchRequestId. You can correct the errors and resubmit the entities in the corresponding POST/bulk-searches request. If returned an error, then the API ignored the entity and no match result is returned for that record. | Code | Description | Tip to Resolve | |------|---------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| | R01 | Merchant DBA Name is required | Submit a valid Merchant DBA Name. | | R02 | Request ID is required | Submit a unique Request ID with the Search API request. | | R03 | State/Province Code is required (Australia, Canada and United States only) | Submit a valid State/Province Code. | | R04 | State/Province Code cannot exceed 3 characters (Australia, Canada and United States only) | Submit a valid State/Province Code. | | R09 | Country Code is required | Submit a valid Country Code. | | R10 | Country Code must be a valid, three-character code | Submit a valid three-character Country Code. | | R23 | Invalid Country and State/Province combination | Submit a valid Country and State/Province combination. | | R24 | U.S. Zip codes must be numeric | Submit numeric U.S. Zip codes such as 11372. | | R51 | Invalid Search Term. Merchant DBA Name is blank after preprocessing. | Make sure you have submitted a valid Merchant DBA Name. | | R52 | Merchant Name must be alphanumeric and the allowed maximum length is 110 | Submit an alphanumeric Merchant Name with a maximum length of 110 characters. | | R53 | Street Address must be alphanumeric and the allowed maximum length is 110 | Submit an alphanumeric Street Address with a maximum length of 110 characters. | | R54 | City must be alpha characters only and the allowed maximum length is 30 | Submit City with alpha characters only and a maximum length of 30 characters. | | R55 | Postal Code must be alphanumeric and the allowed maximum length is 10 | Submit an alphanumeric Postal Code with a maximum length of 10 characters. | | R56 | Phone Number must be alphanumeric and the allowed maximum length is 16 | Submit an alphanumeric Phone Number with a maximum length of 16 characters. | | R57 | Tax ID must be alphanumeric and the allowed maximum length is 15 | Submit an alphanumeric Tax ID with a maximum length of 15 characters. | | R90 | Too many requests received with the same API-Key. Should re-submit the query after a while. | Make sure that your application adheres to the number of request limitations for Track Search. | ## Check status error codes {#check-status-error-codes} The following error codes can be returned when you retrieve the status of a search request using the GET/{bulk_search_id} endpoint. Correct the errors and resubmit the entities in the corresponding POST/bulk-searches request. If returned an error, then the API ignored the entity and no match result is returned for that record. | Reason code | Description | Tip to resolve | |---------------------------|---------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------| | BULK_REQUEST_ID_NOT_EXIST | SearchID `[searchId]` does not exist. | Resubmit the request with a valid searchId. | | INVALID_REQUEST | Provided request parameters are not matching with existing records. | Resubmit the request with valid parameters. The previously provided parameters did not return any results from the database. | ## ISO country and state codes {#iso-country-and-state-codes} For country codes 'USA, AUS, CAN' the following state codes are eligible: | State name | State code | Country code | |--------------------------------------------------|------------|--------------| | Alabama | AL | USA | | Montana | MT | USA | | Alaska | AK | USA | | Nebraska | NE | USA | | American Samoa | AS | USA | | Nevada | NV | USA | | Arizona | AZ | USA | | New Hampshire | NH | USA | | Arkansas | AR | USA | | New Jersey | NJ | USA | | California | CA | USA | | New Mexico | NM | USA | | Colorado | CO | USA | | New York | NY | USA | | Connecticut | CT | USA | | North Carolina | NC | USA | | Delaware | DE | USA | | North Dakota | ND | USA | | District of Columbia | DC | USA | | Northern Mariana Is | MP | USA | | Federated States Of Micronesia | FM | USA | | Ohio | OH | USA | | Florida | FL | USA | | Oklahoma | OK | USA | | Georgia | GA | USA | | Oregon | OR | USA | | Guam | GU | USA | | Palau | PW | USA | | Hawaii | HI | USA | | Pennsylvania | PA | USA | | Idaho | ID | USA | | Puerto Rico | PR | USA | | Illinois | IL | USA | | Rhode Island | RI | USA | | Indiana | IN | USA | | South Carolina | SC | USA | | Iowa | IA | USA | | South Dakota | SD | USA | | Kansas | KS | USA | | Tennessee | TN | USA | | Kentucky | KY | USA | | Texas | TX | USA | | Louisiana | LA | USA | | Utah | UT | USA | | Maine | ME | USA | | Vermont | VT | USA | | Marshall Islands | MH | USA | | Virgin Islands | VI | USA | | Maryland | MD | USA | | Virginia | VA | USA | | Massachusetts | MA | USA | | West Australia, Washington | WA | USA, AUS | | Michigan | MI | USA | | West Virginia | WV | USA | | Minnesota | MN | USA | | Wisconsin | WI | USA | | Mississippi | MS | USA | | Wyoming | WY | USA | | Missouri | MO | USA | | Armed Forces Americas (except Canada) | AA | USA | | Armed Forces Europe, the Middle East, and Canada | AE | USA | | Armed Forces Europe, the Middle East, and Canada | AP | USA | | Alberta | AB | CAN | | Nunavut | NU | CAN | | British Columbia | BC | CAN | | Ontario | ON | CAN | | Manitoba | MB | CAN | | Prince Edward Island | PE | CAN | | New Brunswick | NB | CAN | | Quebec | QC | CAN | | Newfoundland and Labrador | NL | CAN | | Saskatchewan | SK | CAN | | Northwest Territories, Northern Territory | NT | CAN, AUS | | Yukon | YT | CAN | | Nova Scotia | NS | CAN | | Australian Capital Territory | ACT | AUS | | South Australia | SA | AUS | | New South Wales | NSW | AUS | | Tasmania | TAS | AUS | | Victoria | VIC | AUS | | Queensland | QLD | AUS |