HTTP Response Codes

A 207 or other response code, many of which are listed below, indicates the data you requested cannot be returned for a variety of reasons. For example, if an incorrect city, state and zip are provided as input, it is very unlikely the API will be able to find the correct match in the directory and you may see a message similar to the one below indicating a low Markaaz match confidence score. The format of 207 responses will always include a traceId, a message, a markaazMatchConfidenceScore, and a messageID. The message will provide insight into why a 200 response was not returned. Your integration should check the response code and handle the exceptions (non 200 responses) appropriately. Your integration code should check the messageId and apply your business rules for a resolution. In the example below, it would be wise to verify the legal name and address of the business since the data provided resulted in a low markaazMatchConfidenceScore and perhaps submit the request again.

🚧

Markaaz reserves the right to update, edit, or clarify the "message" text for any non-200 HTTP response without creating a new version of the API's. This means you should not parse out the message text, evaluate or rely on specific message text in any integration logic. You may, and should use the messageId for any integration logic in your message handler to inform the calling routine. Markaaz will maintain the messageId's and the spirit or intent of the message text to convey what happened as a result of the API call.

{  
  "markaaz": {  
    "traceId": "",  
    "message": "Did not meet the high confidence match set",  
    "markaazMatchConfidenceScore": 4.32,  
    "messageId": 1001  
  }  
}

207 Response Codes:

400 Series Response Codes

400 response codes take on the following format:

• A traceId which is used by Markaaz to diagnose any issues or otherwise understand an API call / request.
• A message indicating what has caused the error.
• A 4-digit messageId used to easily handle specific situations / error conditions in your integration code.
• In some situations, additional information is provided in the form of errors as shown in Message ID 4001 below.

Anytime a 400 series response is received, the response body as shown below, should be written to your log file to aid Markaaz in troubleshooting the issue should it persist.

{
    "markaaz": {
        "traceId": "cd2918b3-50f9-4ede-b8c8-159b8d7abff5",
        "message": "Resource not found",
        "messageId": 4115
    }
}

{
    "markaaz": {
        "traceId": "fdb9a037-d690-4f95-bba1-12e642bca1a1",
        "message": "failed - missing required field.",
        "messageId": 4001,
        "errors": {
            "bizInfo": {
                "postalCode": [
                    "This field may not be blank."
                ],
                "country": [
                    "\"GERMANY\" is not a valid choice."
                ]
            }
        }
    }
}

4000 Series Messages

4100 series messages

500 Response Codes

500 response codes take on the following format:

• A traceId which is used by Markaaz to diagnose any issues or otherwise understand an API call / request.
• A message indicating what has caused the error.
• A 4-digit messageId used to easily handle specific situations / error conditions in your integration code.
• In some situations, additional information is provided in the form of errors where one or more issues are identified.

{
  "markaaz": {
    "traceId": "<string>",
    "message": "<string>",
    "messageId": "<number>",
    "errors": "<string>"
  }
}

Anytime a 500 series error is received, the response (as shown below) should be written to your log file to aid Markaaz in troubleshooting the issue should it persist.

 {  
    "markaaz": {  
        "traceId": "8db76129-bd5b-417c-8e9a-c5dfe813f9e4",  
        "message": "Endpoint request timed out",  
        "messageId": 5105  
    }  
}