Error Handling¶

All Toolkit API endpoints use standard HTTP status codes and return consistent JSON error bodies.

Error Response Format¶

Every error response includes a detail field with a human-readable message:

{
  "detail": "Invalid domain format: must be a valid FQDN"
}

Some endpoints include additional context:

{
  "detail": "Validation error",
  "errors": [
    {"field": "email", "message": "Not a valid email address"},
    {"field": "timeout", "message": "Must be between 1 and 30"}
  ]
}

Status Codes¶

Handling Errors in Code¶

Python¶

import httpx

r = httpx.get(
  "https://dns.toolkitapi.io/v1/lookup",
    headers={"X-API-Key": "YOUR_KEY"},
  params={"domain": "toolkitapi.io", "type": "A"},
)

if r.status_code == 200:
    data = r.json()
elif r.status_code == 429:
    print("Rate limited — back off and retry")
elif r.status_code >= 400:
    error = r.json()
    print(f"Error {r.status_code}: {error.get('detail', 'Unknown error')}")

JavaScript¶

const response = await fetch("https://dns.toolkitapi.io/v1/lookup?domain=toolkitapi.io&type=A", {
  headers: {
    "X-API-Key": "YOUR_KEY",
  },
});

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

Retry Strategy¶

For transient errors (429, 500, 504), implement exponential backoff:

1. Wait 1 second, retry
2. Wait 2 seconds, retry
3. Wait 4 seconds, retry
4. Give up and surface the error