HTTP Response Codes¶
The DNSDB API uses standard HTTP response codes to indicate the success or failure of requests.
Success Codes¶
| Response Code | Description |
|---|---|
| 200 OK | The 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¶
| Response Code | Description |
|---|---|
| 400 Bad Request | The URL is formatted incorrectly, such as unrecognized lower-level components. |
| 401 Unauthorized | Your API key may not query this API version, or the API key is not authorized (usually indicates the block quota is expired). |
| 403 Forbidden | The 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 Found | The 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 Type | The Accept: header does not specify a supported content type for this query. |
| 416 Requested Range Not Satisfiable | The offset value is greater than the maximum allowed or if an offset value was provided when not permitted. |
| 429 Too Many Requests | You 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¶
| Response Code | Description |
|---|---|
| 500 Internal Server Error | There is an error processing the request. Returns text/html content type regardless of what was requested. |
| 503 Service Unavailable | The limit of number of concurrent connections is exceeded. |
| 504 Gateway Timeout | The 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¶
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¶
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¶
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:
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: