HTTP Response Codes
Each API request will subsequently receive one of the following response codes: 200, 207, 400, or 500 series codes. A 200 response indicates that Markaaz found the information requested and will be delivered in the documented response format in the API Reference section.
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:
MessageID | Response | Notes |
---|---|---|
1001 | { "markaaz": { "traceId": "", "message": "Did not meet the high confidence match set", "markaazMatchConfidenceScore": 4.32, "messageId": 1001 } } | Did not meet the high confidence match set |
1002 | { "markaaz": { "traceId": "", "message": "Unable to locate business!", "markaazMatchConfidenceScore": 0, "messageId": 1002 } } | Unable to locate business! |
1003 | { "markaaz": { "traceId": "", "message": "Invalid Markaaz Id", "markaazMatchConfidenceScore": null, "messageId": 1003 } } | Invalid Markaaz ID |
1004 | { "markaaz": { "traceId": "", "message": "No company primary contact or company officers found.", "messageId": 1004 } } | No company primary contact or company officers found. |
1005 | { "markaaz": { "traceId": "", "message": "No names provided for matching.", "messageId": 1005 } } | No names provided for matching. |
1006 | { "markaaz": { "traceId": "", "message": "Invalid Portfolio Id.", "messageId": 1006 } } | The portfolio ID does not exist or the portfolio is not associated with this enterprise partner. |
1007 | { "markaaz": { "traceId": "", "message": "Invalid Monitoring Type, valid values are business and / or compliance.", "messageId": 1007 } } | Invalid Monitoring Type, valid values are business and / or compliance |
1008 | { "markaaz": { "traceId": "", "message": "Disable monitoring is only available for monitored records.", "messageId": 1008 } } | Disable monitoring is only available for monitored records. (This is the response if the input seeks to disable an unmonitored entry.) |
1009 | { "markaaz": { "traceId": "", "message": "Monitoring must be disabled before an entity is removed.", "messageId": 1009 } } | An entity shall not be removed from a portfolio until all monitoring on that entity has been disabled. |
1010 | { "markaaz": { "traceId": "", "message": "The Markaaz ID provided does not have any company hierarchy.", "messageId": 1010 } } | This response can be avoided by checking the hasCompanyHierarchy value in the firmographic object. |
1012 | { "markaaz": { "traceId": "", "message": "The Markaaz ID provided does not exist in the portfolio.", "messageId": 1012 } } | Markaaz ID's must exist in the portfolio before actions can be taken. |
1013 | { "markaaz": { "traceId": "", "message": "The epInternalId provided does not exist in the portfolio.", "messageId": 1013 } } | The Enterprise Partner Internal ID cannot be found in the portfolio based on the information provided. |
1016 | { "markaaz": { "traceId": "", "message": "Unable to add entity. It already exists in the portfolio.", "messageId": 1016 } } | An entity cannot be added twice to a portfolio. |
1017 | { "markaaz": { "traceId": "", "message": "Unable to remove entity. It does not exist in the portfolio.", "messageId": 1017 } } | The entity does not exist in the portfolio and cannot be removed. |
1020 | { "markaaz": { "traceId": "", "message": "Compliance monitoring is only enabled for monitored record", "messageId": 1020 } } | Message is changing: "Unable to complete request. Compliance monitoring is either already disabled or it was never enabled." |
1021 | { "markaaz": { "traceId": "", "message":Business monitoring is only enabled for monitored record", "messageId": 1021 } } | Message is changing: "Unable to complete request. Business monitoring is either already disabled or it was never enabled." |
1023 | { "markaaz": { "traceId": "", "message":Compliance or/and Business Monitoring Already Enabled", "messageId": 1022 } } | |
1024 | { "markaaz": { "traceId": "", "message":Markaaz ID is currently unavailable or not associated with any portfolio.", "messageId": 1024 } } | |
1025 | { "markaaz": { "traceId": "", "message": "Based on the inputs provided, the score of the best search did not meet the Markaaz Search Confidence Threshold for high confidence", "messageId": 1025 } } | It is unlikely this message will ever be received unless the client has requested a configuration change of the search confidence threshold setting. |
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
MessageID | HTTP Response | Notes |
---|---|---|
4001 | { "markaaz": { "traceId": "", "message": "", "messageId": "", "errors": "" } } | Failed - missing required field, errors may contain multiple error conditions found |
4002 | { "markaaz": { "traceId": "", "message": "Missing required request parameters: [x-partner-id]", "messageId": 4002 } } | The Partner ID is required. |
4003 | { "markaaz": { "traceId": "", "message": "Partner ID doesn't exist", "messageId": 4003 } } | The Partner ID provided is unknown. |
4004 | { "markaaz": { "traceId": "", "message": "Invalid request body", "messageId": 4004 } } | Invalid request body. |
4005 | { "markaaz": { "traceId": "", "message": "Invalid Portfolio Id", "messageId": 4105 } } | A call to the portfolio list API will confirm what portfolio IDs are available. |
4006 | { "markaaz": { "traceId": "", "message": "Monitoring APIs are not enabled for your account", "messageId": 4106 } } | Monitoring APIs are not enabled for your account. |
4007 | Invalid Partner ID. |
4100 series messages
MessageID | HTTP Response | Notes |
---|---|---|
4100 | API Gateway - Access Denied | |
4101 | { "markaaz": { "traceId": "", "message": "Invalid request body", "messageId": 4101 } } | API Gateway error, bad request body. |
4102 | { "markaaz": { "traceId": "", "message": "API Gateway - Bad Request Parameters", "messageId": 4102 } } | API Gateway - Bad Request Parameters |
4103 | { "markaaz": { "traceId": "", "message": "API Gateway - Default 400", "messageId": 4103 } } | API Gateway - Default 4XX |
4104 | { "markaaz": { "traceId": "", "message": "API Gateway - Expired Token", "messageId": 4104 } } | API Gateway - Expired Token |
4105 | { "markaaz": { "traceId": "", "message": "Forbidden", "messageId": 4105 } } | API Gateway error, Invalid API Key |
4106 | { "markaaz": { "traceId": "", "message": "API Gateway - Invalid Signature", "messageId": 4106 } } | API Gateway - Invalid Signature |
4107 | { "markaaz": { "traceId": "", "message": "API Gateway - Missing Authentication Token", "messageId": 4107 } } | API Gateway - Missing Authentication Token |
4108 | { "markaaz": { "traceId": "", "message": "API Gateway - Quota Exceeded", "messageId": 4108 } } | API Gateway - Quota Exceeded |
4109 | { "markaaz": { "traceId": "", "message": "API Gateway - Request Too Large", "messageId": 4109 } } | API Gateway - Request Too Large |
4110 | { "markaaz": { "traceId": "", "message": "API Gateway - Resource Not Found", "messageId": 4110 } } | API Gateway - Resource Not Found |
4111 | { "markaaz": { "traceId": "", "message": "API Gateway - Throttled", "messageId": 4111 } } | API Gateway - Throttled |
4112 | { "markaaz": { "traceId": "", "message": "API Gateway - Unauthorized", "messageId": 4112 } } | API Gateway - Unauthorized |
4113 | { "markaaz": { "traceId": "", "message": "API Gateway - Unsupported Media Type", "messageId": 4113 } } | API Gateway - Unsupported Media Type |
4114 | { "markaaz": { "traceId": "", "message": "API Gateway - WAF Filtered", "messageId": 4114 } } | API Gateway - WAF Filtered |
4115 | { "markaaz": { "traceId": "", "message": "Access Denied: You do not have the required permissions to perform this action. Please contact your administrator for assistance", "messageId": 4115 } } | 403 - You do not have permission to call the API. Generally this means you are not contracted to use the API being called. |
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
}
}
MessageID | HTTP Response | Notes |
---|---|---|
5001 | { "markaaz": { "traceId": "", "message": "Failed to process the API request. Please try again later. If the problem persists, please contact support", "messageId": 5001, "errors": "Specific Error Text" } } | errors text may vary, text may provide more information as to the cause of the error. |
5100 | { "markaaz": { "traceId": "", "message": "Endpoint request timed out", "messageId": 5105 } } | API Gateway - API Configuration Error |
5101 | { "markaaz": { "traceId": "", "message": "API Gateway - Authorizer Configuration Error", "messageId": 5101 } } | API Gateway - Authorizer Configuration Error |
5102 | { "markaaz": { "traceId": "", "message": "API Gateway - Authorizer Failure", "messageId": 5102 } } | API Gateway - Authorizer Failure |
5103 | { "markaaz": { "traceId": "", "message": "API Gateway - Default 500", "messageId": 5103 } } | API Gateway - Default 500 |
5104 | { "markaaz": { "traceId": "", "message": "Network error communicating with endpoint", "messageId": 5104 } } | 504 Response: A network error has occurred. |
5105 | { "markaaz": { "traceId": "", "message": "Endpoint request timed out", "messageId": 5105 } } | 504 Response: The system is taking too long to respond. |
Updated 5 days ago