API Error Codes
Our API uses standard HTTP status codes to indicate the success or failure of a request. In general, codes in the 2xx range indicate success, codes in the 4xx range indicate a client-side error (e.g., a problem with the request), and codes in the 5xx range indicate a server-side error.
When an error occurs, the API will return a JSON response body with more details about the error.
Standard Error Response
A typical error response follows this format:
{
"status": <HTTP_STATUS_CODE>,
"message": "<ERROR_MESSAGE>"
}
Common HTTP Status Codes
Below is a summary of the most common HTTP status codes you may encounter.
Client Errors (4xx)
| Status Code | Message | Description |
|---|---|---|
| 400 Bad Request | Bad Request | The server could not understand the request due to invalid syntax. This could be caused by a malformed JSON body or invalid parameters. |
| 401 Unauthorized | Unauthorized | Your API key is missing, invalid, or expired. Please check your X-API-KEY header and ensure your key is active. |
| 403 Forbidden | Forbidden | You do not have permission to access this resource. This may be due to insufficient subscription plan privileges or other access restrictions. |
| 404 Not Found | Not Found | The requested resource could not be found. This often occurs when querying for a domain or host that does not exist in our database. |
| 429 Too Many Requests | Too Many Requests | You have exceeded your rate limit. Please refer to our Rate Limiting Guide and implement a retry mechanism with exponential backoff. |
Server Errors (5xx)
| Status Code | Message | Description |
|---|---|---|
| 500 Internal Server Error | Internal Server Error | We had a problem with our server. Please try again later. If the problem persists, please contact our support team. |
| 502 Bad Gateway | Bad Gateway | Our servers are temporarily unable to handle the request. This is usually a transient issue. Please try again in a few moments. |
| 503 Service Unavailable | Service Unavailable | The service is temporarily down for maintenance or is overloaded. Please try again later. Check our status page for more information. |