HTTP Response Codes
Each API request will subsequently receive one of the following response codes: 200, 207, 400, 403, or 500. 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": {
"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 | ||
1021 | ||
1023 | ||
1024 |
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 | API Gateway - Bad Request Parameters | |
4103 | API Gateway - Default 4XX | |
4104 | API Gateway - Expired Token | |
4105 | { "markaaz": { "traceId": "", "message": "Forbidden", "messageId": 4105 } } | API Gateway error, Invalid API Key |
4106 | 403 | API Gateway - Invalid Signature |
4107 | 403 | API Gateway - Missing Authentication Token |
4108 | 429 | API Gateway - Quota Exceeded |
4109 | 413 | API Gateway - Request Too Large |
4110 | 404 | API Gateway - Resource Not Found |
4111 | 429 | API Gateway - Throttled |
4112 | 404 | API Gateway - Unauthorized |
4113 | 415 | API Gateway - Unsupported Media Type |
4114 | 403 | API Gateway - WAF Filtered |
4115 | { "markaaz": { "traceId": "", "message": "Resource not found", "messageId": 4115 } } | API Gateway - 404. (This could be the result of calling an invalid endpoint.) |
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" } } | Specific Error Text may provide more information as to the cause of the error. |
5100 | 500 | API Gateway - API Configuration Error |
5101 | 500 | API Gateway - Authorizer Configuration Error |
5102 | 500 | API Gateway - Authorizer Failure |
5103 | 500 | API Gateway - Default 5XX |
5104 | 504 | 504 Response: Integration Failure |
5105 | { "markaaz": { "traceId": "", "message": "Endpoint request timed out", "messageId": 5105 } } | 504 Response: The system is taking too long to respond. |
Updated 7 days ago