Error Handling

The CronDB API uses standard HTTP status codes and returns structured error responses to help you diagnose and handle issues.

Error Response Format

All error responses return a JSON object with a detail field:

{
  "detail": "Domain not found in database"
}

Some errors include additional context:

{
  "detail": "Validation error",
  "errors": [
    {
      "field": "domain",
      "message": "Invalid domain format"
    }
  ]
}

HTTP Status Codes

Success Codes

Code	Meaning	Description
200	OK	Request succeeded
201	Created	Resource created successfully
202	Accepted	Request accepted for async processing (bulk operations)
204	No Content	Request succeeded, no response body

Client Error Codes

Code	Meaning	Common Causes
400	Bad Request	Invalid parameters, malformed JSON
401	Unauthorized	Missing or invalid API key
403	Forbidden	Account suspended, insufficient plan
404	Not Found	Domain not in database, invalid endpoint
409	Conflict	Resource already exists
422	Unprocessable Entity	Valid JSON but invalid field values
429	Too Many Requests	Rate limit exceeded

Server Error Codes

Code	Meaning	Description
500	Internal Server Error	Unexpected server-side error
502	Bad Gateway	Upstream service unavailable
503	Service Unavailable	API is temporarily down for maintenance

Common Errors and Solutions

400 Bad Request

Invalid domain format:

{"detail": "Validation error", "errors": [{"field": "domain", "message": "Invalid domain format"}]}

Solution: Ensure the domain is a valid format (e.g., example.com, not https://example.com or www.example.com).

Missing required parameter:

{"detail": "Validation error", "errors": [{"field": "domain", "message": "This field is required"}]}

Solution: Include all required parameters in your request.

401 Unauthorized

{"detail": "Invalid API key"}

Solution:

• Verify your API key is correct
• Check that the Authorization header uses the Bearer prefix
• Ensure the key has not been revoked

404 Not Found

{"detail": "Domain not found in database"}

Solution: The domain is not yet in CronDB's database. This can happen with very new or obscure domains. Not every registered domain has been crawled.

429 Too Many Requests

{"detail": "Rate limit exceeded. Try again in 32 seconds."}

Solution:

• Check the Retry-After header for when to retry
• Implement exponential backoff
• Consider upgrading your plan for higher rate limits
• Use bulk endpoints to reduce request count

500 Internal Server Error

{"detail": "Internal server error"}

Solution:

• Retry the request after a short delay
• If persistent, contact support with the X-Request-ID header value

Error Handling Best Practices

Python

import requests

response = requests.get(
    "https://api.crondb.com/v1/enrichment/domain",
    params={"domain": "example.com"},
    headers={"Authorization": "Bearer cdb_your_key"},
)

if response.status_code == 200:
    data = response.json()
    # Process data
elif response.status_code == 401:
    print("Authentication failed. Check your API key.")
elif response.status_code == 404:
    print("Domain not found in CronDB database.")
elif response.status_code == 429:
    retry_after = int(response.headers.get("Retry-After", 60))
    print(f"Rate limited. Retry after {retry_after}s.")
elif response.status_code >= 500:
    print(f"Server error ({response.status_code}). Retry later.")
    request_id = response.headers.get("X-Request-ID")
    print(f"Request ID for support: {request_id}")
else:
    print(f"Unexpected error: {response.status_code} — {response.text}")

JavaScript

try {
  const response = await fetch(
    "https://api.crondb.com/v1/enrichment/domain?domain=example.com",
    { headers: { Authorization: "Bearer cdb_your_key" } }
  );

  if (response.ok) {
    const data = await response.json();
    // Process data
  } else if (response.status === 429) {
    const retryAfter = response.headers.get("Retry-After") || 60;
    console.log(`Rate limited. Retry after ${retryAfter}s.`);
  } else {
    const error = await response.json();
    console.error(`Error ${response.status}: ${error.detail}`);
  }
} catch (err) {
  console.error("Network error:", err.message);
}

Request ID for Support

Every response includes an X-Request-ID header. When contacting support, include this ID so we can trace the exact request in our logs.

X-Request-ID: req_a1b2c3d4e5f6

Next Steps

• Authentication — Ensure your API key is correct
• Rate Limits — Understand and handle rate limiting
• API Overview — Review available endpoints