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:

MessageID	Response	Notes
1001	{ "markaaz": { "traceId": "", "message": "Did not meet the high confidence match set", "markaazMatchConfidenceScore": 4.32, "messageId": 1001 } }	Based on your configuration settings, there was not a matching business with results that met your Markaaz Match Score threshold.
1002	{ "markaaz": { "traceId": "", "message": "Unable to locate business!", "markaazMatchConfidenceScore": 0, "messageId": 1002 } }	We were unable to locate a business in our Global Business Directory that matches the data inputs submitted.
1003	{ "markaaz": { "traceId": "", "message": "Invalid Markaaz Id", "markaazMatchConfidenceScore": null, "messageId": 1003 } }	The Markaaz Id submitted is not a valid Markaaz Id in our system.
1004	{ "markaaz": { "traceId": "", "message": "No company primary contact or company officers found.", "messageId": 1004 } }	No company primary contact or company officers were found when searching our Global Business Directory.
1005	{ "markaaz": { "traceId": "", "message": "No names provided for matching.", "messageId": 1005 } }	No names were provided for matching to businesses in the person to business search.
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 } }	Indicates that the business is only enabled for monitoring of compliance changes.
1021	{ "markaaz": { "traceId": "", "message":Business monitoring is only enabled for monitored record", "messageId": 1021 } }	Indicates the business is only enabled for monitoring of business information changes.
1022	{ "markaaz": { "traceId": "", "message":Compliance or/and Business Monitoring Already Enabled", "messageId": 1022 } }	Compliance and Monitoring is already enabled for the Business.
1024	{ "markaaz": { "traceId": "", "message":Markaaz ID is currently unavailable or not associated with any portfolio.", "messageId": 1024 } }	The Markaaz Id no longer exists in Markaaz, or has not been added to any portfolio in your enterprise.
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 } }	Indicates that the results of the business search and match did not meet the score settings for the Markaaz Score setting for the Enterprise. Note: It is unlikely this message will ever be received unless the client has requested a configuration change of the search confidence threshold setting.
1026	{ "markaaz": { "traceId": "", "message": "Lien Data is only available for US Companies", "messageId": 1026 } }	Legal Filing data is only available for businesses in the US.
1027	{ "markaaz": { "traceId": "", "message": "Financial data not available", "messageId": 1027 } }	Financials data is not available for the business associated with the Markaaz Id that was submitted.
1028	{ "markaaz": { "traceId": "", "message": "Financial data not available in [2-Digit Country]", "messageId": 1028 } }	Financials data is not available for the country where the Business associated with the Markaaz Id is located.
1029	{ "markaaz": { "traceId": "", "message": "Financial data not available for this entity", "messageId": 1029 } }	Financials data is not available for the business associated with the Markaaz Id that was submitted.
1030	{ "markaaz": { "traceId": "", "message": "Shareholder data not available for [2-Digit Country]", "messageId": 1030 } }	Shareholder data is not available for the country where the Business associated with the Markaaz Id is located.
1031	{ "markaaz": { "traceId": "", "message": "Shareholder data not available", "messageId": 1031 } }	Shareholder data is not available for the Markaaz Id submitted.

400 Series Response Codes

400 response codes take on the following format:

<string> A traceId which is used by Markaaz to diagnose any issues or otherwise understand an API call / request.
<string> A message indicating what has caused the error.
<integer> 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": `<string>`, "message": `<string>`, "messageId": `<number>`, "errors": `<string>` } }	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": 4005 } }	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": 4006 } }	Monitoring APIs are not enabled for your account.
4007	{ "markaaz": { "traceId": "", "message": "Invalid Partner Id", "messageId": 4007 } }	Indicates your Partner Id is invalid.
4008	{ "markaaz": { "traceId": "", "message": "Could not satisfy the request accept header", "messageId": 4008 } }	Indicates the HTTP client has requested a response using Accept- headers that our server cannot fulfill.
4009	{ "markaaz": { "traceId": "", "message": "convertCurrency must be submitted as a valid 2-digit country code", "messageId": 4009 } }	Indicates the convertCurrency parameter must be submitted in ISO 3166-1 standard for the conversion to be successful.

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:

<string> A traceId which is used by Markaaz to diagnose any issues or otherwise understand an API call / request.
<string> A message indicating what has caused the error.
<integer> 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, but general issues are aligned to standard programming issues. Sharing the text with your support manager 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.