Skip to content
DomainTools Technical Documentation

DNSDB API HTTP response codes

The DNSDB API uses standard HTTP response codes to indicate the success or failure of requests.

Success Codes

Section titled “Success Codes”
Response CodeDescription
200 OKThe request was successfully processed. For requests that stream back data, the server interpreted the request correctly and began to reply, but look at the final “cond” for success or failure of returning the streamed data.

Client Error Codes

Section titled “Client Error Codes”
Response CodeDescription
400 Bad RequestThe URL is formatted incorrectly, such as unrecognized lower-level components.
401 UnauthorizedYour API key may not query this API version, or the API key is not authorized (usually indicates the block quota is expired).
403 ForbiddenThe X-API-Key header is not present, the provided API key is not valid, or the Client IP address is not authorized for this API key.
404 Not FoundThe URL path had unrecognized or missing top-level components.

Note: In APIv1 this error indicated that there were no results found. In APIv2, this is not an error - a 200 OK is returned with no “obj” lines in the SAF response.
415 Unsupported Media TypeThe Accept: header does not specify a supported content type for this query.
416 Requested Range Not SatisfiableThe offset value is greater than the maximum allowed or if an offset value was provided when not permitted.
429 Too Many RequestsYou have exceeded your quota and no new requests will be accepted at this time.

For time-based quotas: The API key’s daily quota limit is exceeded. The quota will automatically replenish, usually at the start of the next day.

For block-based quotas: The block quota is exhausted. You may need to purchase a larger quota.

For burst rate secondary quotas: There were too many queries within the burst window. The window will automatically reopen at its end.

Server Error Codes

Section titled “Server Error Codes”
Response CodeDescription
500 Internal Server ErrorThere is an error processing the request. Returns text/html content type regardless of what was requested.
503 Service UnavailableThe limit of number of concurrent connections is exceeded.
504 Gateway TimeoutThe DNSDB Server timed-out before returning any results. Your query might be too complex, such as doing a wildcard search with restrictive time-fencing. You might simplify the query and retry it.

Content Types by Response

Section titled “Content Types by Response”

Different response types return different content types:

  • Successful data responses (200 OK): Returns the content type specified in the Accept header (e.g., application/x-ndjson)
  • 500 Internal Server Error: Returns text/html (no matter what was requested)
  • Other API errors: Return text/plain (no matter what was requested)
  • nginx errors (e.g., 404 for unknown URL): Return text/html

Examples

Section titled “Examples”

Successful Query

Section titled “Successful Query”
curl -i -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com?limit=1"

Response:

HTTP/1.1 200 OK
Content-Type: application/x-ndjson
X-RateLimit-Limit: 1000
X-RateLimit-Remaining: 999
X-RateLimit-Reset: 1433980800


{"cond": "begin"}
{"obj":{...}}
{"cond": "succeeded"}

Bad Request

Section titled “Bad Request”
curl -i -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/name/fsi.io"

Response:

HTTP/1.1 400 Bad Request
Content-Type: text/plain


Error: unable to parse request

Rate Limit Exceeded

Section titled “Rate Limit Exceeded”
curl -i -H "Accept: application/x-ndjson" -H "X-API-Key: $DNSDB_API_KEY" \
  "https://api.dnsdb.info/dnsdb/v2/lookup/rrset/name/example.com"

Response:

HTTP/1.1 429 Too Many Requests
Content-Type: text/plain


Error: Rate limit exceeded