Errors¶
All error responses sent by the API have a unified structure. Each error
response contains two contextual keys: query and
error.error_context. The former just mirrors specified request
parameters while the latter contains contextual error data that is specific
for an endpoint to which the request was sent.
See Error Types for a list of all defined errors.
Structure¶
-
Error Response¶ General structure of an error response.
Object Properties: - query (object) – Contextual information about the query that was performed. Essentially, this object just mirrors request parameters that were specified (after a disambiguation and resolution process). Object structure is defined individually for each API endpoint. See Query Object for a half-decent generalization of this object’s structure. May be absent.
- error (
Error Object) – Error object that was returned. Always present.
-
Error Object¶ Error object structure.
Object Properties: - error_name (string) – Name of an error that occured. Always present.
- error_desc (string) – Description of an error that occured. It is static and is defined by the error itself, not a request that was sent. Always present.
- error_context (object) – A nested object with a contextual information about the error. Object structure is defined individually for each API endpoint. May be absent.
Examples¶
An example of a full-fledged error response:
{
"query": {
"action": "search_subdomains",
"parameters": {
"domain": "example.com",
"iv.history": true
}
},
"error": {
"error_name": "bad_request",
"error_description": "Request is malformed",
"error_context": {
"invalid_parameter_name": "iv.history",
"valid_parameter_names": [
"ipv4.history",
"ipv4.latest",
"ipv4.live",
"ipv4.meta",
"ipv4.oldest",
"ipv6.history",
"ipv6.latest",
"ipv6.live",
"ipv6.meta",
"ipv6.oldest"
]
}
}
}
Error Types¶
The majority of error types are tied to a specific HTTP status code though this is not always the case (i.e. both Empty Result and No Such Endpoint are returned with 404 Not Found). It is advised to always check the response body to determine which type of error has occured.
While the majority of API errors are documented here, there is a chance that client will receive an undocumented error. These can be treated according to HTTP response status they are returned with completely ignoring the response body.
Bad Request¶
Request object structure is malformed. This error usually contains more information about what is exactly malformed in error.error_context object. Context object structure usually differs depending on an endpoint.
| HTTP Status Code | Error Name | Error Description |
| 400 Bad Request | bad_request |
Request object structure is malformed |
Example:
{
"query": {
"action": "search_subdomains",
"parameters": {
"domain": "69"
}
},
"error": {
"error_name": "bad_request",
"error_description": "Request is malformed",
"error_context": {
"invalid_parameter_value": "69"
}
}
}
Empty Result¶
Request was successfully processed but yielded no results. This error is often sent in conjunction with 404 Not Found HTTP status code thus making it similar to No Such Endpoint. Do check the response body to correctly handle these errors.
| HTTP Status Code | Error Name | Error Description |
| 404 Not Found | empty_result |
Request produced no results |
Example:
{
"query": {
"action": "search_subdomains",
"parameters": {
"domain": "abcabcabcabcabcabcabcabcabcabcabcabcabc.io",
"ipv4.history": false,
"ipv4.latest": true,
"ipv4.live": false,
"ipv4.meta": false,
"ipv4.oldest": true,
"ipv6.history": false,
"ipv6.latest": true,
"ipv6.live": false,
"ipv6.meta": false,
"ipv6.oldest": true
}
},
"error": {
"error_name": "empty_result",
"error_description": "Request produced no results"
}
}
Internal Server Error¶
Internal server error. This is most probably a bug. See Bugs Reporting for more information about how to report bugs and security vulnerabilities.
| HTTP Status Code | Error Name | Error Description |
| 500 Internal Server Error | internal_server_error |
API server failed to process the request |
Example:
{
"error": {
"error_name": "internal_server_error",
"error_description": "API server failed to process the request"
}
}
Method Not Allowed¶
Requested endpoint does not support HTTP method that was used. Query Object is not returned when this error occurs.
| HTTP Status Code | Error Name | Error Description |
| 405 Method Not Allowed | method_not_allowed |
Request method is not supported by this endpoint |
Example:
{
"error": {
"error_name": "method_not_allowed",
"error_description": "Request method is not supported by this endpoint"
}
}
No Such Endpoint¶
Requested API endpoint does not exist. Query Object is not returned when this error occurs.
| HTTP Status Code | Error Name | Error Description |
| 404 Not Found | no_such_endpoint |
Requested API endpoint does not exist |
Example:
{
"error": {
"error_name": "no_such_endpoint",
"error_description": "Requested API endpoint does not exist"
}
}
Rate Limit Exceeded¶
| HTTP Status Code | Error Name | Error Description |
| 429 Too Many Requests | rate_limit_exceeded |
API rate limit was exceeded |
Todo
Propertly document Rate Limit Exceeded error type
Processing Timeout¶
Note
This error indicates that a hard limit for resources utilization was reached and no further processing will be made for this request. This is a current limitation of the API. Processing timeout will be increasing in the near future.
Request took too long to process and was abandoned by the API server. No results will be returned.
| HTTP Status Code | Error Name | Error Description |
| 501 Not Implemented | processing_timeout |
Request processing took too long |
{
"query": {
"action": "search_subdomains",
"parameters": {
"domain": "example.com",
"ipv4.history": true,
"ipv4.latest": true,
"ipv4.live": true,
"ipv4.meta": true,
"ipv6.history": true,
"ipv4.oldest": true,
"ipv6.latest": true,
"ipv6.live": true,
"ipv6.meta": true,
"ipv6.oldest": true
}
},
"error": {
"error_name": "processing_timeout",
"error_description": "Request processing took too long"
}
}