Skip to main content

​
Overview

The DNSRadar API uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success, codes in the 4xx range indicate an error caused by the provided information, and codes in the 5xx range indicate an error with DNSRadar’s servers.

​
Error Response Format

When an error occurs, the API returns a JSON response with the following structure: 
{
  "code": 400,
  "error": "Invalid request parameters",
  "errors": {
    "domain": "Domain name is required",
    "record_type": "Must be one of: A, AAAA, CNAME, MX, TXT, NS, PTR"
  }
}
​
code
integer
HTTP status code indicating the error type
​
error
string
Human-readable error message describing what went wrong
​
errors
object
Field-specific validation errors (present for 400 Bad Request responses)

​
HTTP Status Codes

​
Success Codes

CodeStatusDescription
200OKRequest succeeded. The response body contains the requested data.
204No ContentRequest succeeded with no response body (typically for DELETE operations).

​
Client Error Codes

Your request is invalid or malformed. This typically means:
  • A required parameter is missing
  • A parameter has an invalid value
  • The request body is not valid JSON
  • Validation constraints are not met
Example:
{
  "code": 400,
  "errors": {
    "expected_value": "Must provide at least one value",
    "frequency": "Must be one of: 5, 10, 15, 30, 60, 120"
  }
}
How to fix: Check the errors object in the response for specific field-level validation errors.
No API key was provided in the request header.Example:
{
  "code": 401,
  "error": "Unauthorized"
}
How to fix: Include your API key in the X-Api-Key header. See Authentication for details.
Your request requires a premium subscription or you’ve reached your plan limits.Example:
{
  "code": 402,
  "error": "Monitor limit reached. Upgrade to create more monitors."
}
How to fix: Upgrade your plan in the Dashboard or remove existing monitors.
The API key provided is invalid, expired, or has been revoked.Example:
{
  "code": 403,
  "error": "Invalid API key"
}
How to fix: Verify your API key is correct or generate a new one from the Dashboard.
The requested resource does not exist or you don’t have access to it.Example:
{
  "code": 404,
  "error": "Monitor not found"
}
How to fix: Check that the resource UUID is correct and belongs to your organization.
The HTTP method used is not supported for this endpoint.Example:
{
  "code": 405,
  "error": "Method not allowed"
}
How to fix: Use the correct HTTP method (GET, POST, PATCH, DELETE) as specified in the API documentation.
You’ve exceeded the rate limit for API requests.Example:
{
  "code": 429,
  "error": "Rate limit exceeded"
}
How to fix: Wait for the rate limit to reset (check X-RateLimit-Reset header) or implement exponential backoff. See Rate Limiting for details.

​
Server Error Codes

An unexpected error occurred on DNSRadar’s servers.Example:
{
  "code": 500,
  "error": "Internal server error"
}
How to fix: This is a server-side issue. Retry your request after a brief wait. If the problem persists, contact support@dnsradar.dev.
The API is temporarily unavailable, typically due to maintenance.How to fix: Wait a few minutes and retry your request. Check our status page for updates.

​
Handling Errors

Here’s how to properly handle errors in your code: 
try {
  const response = await fetch('https://api.dnsradar.dev/monitors', {
    headers: { 'X-Api-Key': apiKey }
  });

  if (!response.ok) {
    const error = await response.json();
    console.error(`Error ${error.code}: ${error.error}`);

    if (error.errors) {
      // Handle validation errors
      Object.entries(error.errors).forEach(([field, message]) => {
        console.error(`${field}: ${message}`);
      });
    }
  }
} catch (err) {
  console.error('Network error:', err);
}
If you encounter an error not listed here or need assistance, contact us at support@dnsradar.dev with the request ID from the response headers.