Iris API Error Codes

The Iris API uses standard HTTP status codes to indicate the success or failure of requests. Understanding these codes helps you handle errors gracefully and troubleshoot issues effectively.

Status Codes

Status Code	Description
200	OK - The request was successful.
206	Partial Content - The request was partially successful. Some data is unavailable but the request returned what was available. This typically occurs when backend services are temporarily unavailable or when data for some requested items cannot be retrieved.
400	Bad Request - The request is malformed or contains invalid parameters. Check the error message for details about what needs to be corrected.
401	Unauthorized - Authentication credentials are missing, invalid, or expired. Verify your API key and authentication method.
403	Forbidden - The authenticated account does not have permission to access this resource or endpoint. This may indicate insufficient subscription level or access rights.
404	Not Found - The requested resource does not exist. This may occur when querying for a domain that has never been registered or for data that is not available in our systems.
500	Internal Server Error - An unexpected error occurred on the server. If this persists, contact DomainTools support at enterprisesupport@domaintools.com.
503	Service Unavailable - The service is temporarily unavailable, typically due to maintenance or high load. Implement exponential backoff and retry the request.

Error Response Format

Error responses follow a consistent JSON structure:

{
  "error": {
    "code": 400,
    "message": "Invalid domain name format"
  }
}

Common Error Scenarios

Authentication Errors (401)

Cause: Missing or invalid API credentials.

Solutions:

• Verify your API key is correct
• Check that your authentication method (header, HMAC, or basic auth) is properly configured
• Ensure your API key hasn’t expired

Authorization Errors (403)

Cause: Insufficient permissions or subscription level.

Solutions:

• Verify your account has access to the requested endpoint
• Check your subscription includes the API product you’re trying to use
• Contact your account manager if you need additional access

Not Found Errors (404)

Cause: Requested resource doesn’t exist.

Common scenarios:

• Querying a domain that has never been registered
• Requesting historical data that predates our records
• Using an invalid endpoint path

Rate Limiting (503)

Cause: Too many requests in a short time period.

Solutions:

• Implement exponential backoff retry logic
• Check your rate limits using the Account Information endpoint
• Distribute requests over time rather than in bursts
• Consider upgrading your subscription for higher rate limits

Best Practices

1. Always check status codes: Don’t assume success - verify the response status code
2. Parse error messages: Error messages contain specific details about what went wrong
3. Implement retry logic: Use exponential backoff for 500 and 503 errors
4. Log errors: Keep detailed logs of errors for troubleshooting
5. Monitor rate limits: Track your API usage to avoid hitting limits

Iris-Specific Notes

Partial Content (206)

The Iris Enrich and Investigate endpoints may return a 206 status code when:

• Some backend data sources are temporarily unavailable
• Data for certain requested domains cannot be retrieved
• The response contains partial results rather than complete data

When you receive a 206 response, the returned data is still valid and usable - it simply indicates that some information is missing.

Detect Endpoints

Iris Detect endpoints (watchlists and monitors) use a subset of the standard error codes:

• 200 (OK)
• 400 (Bad Request)
• 401 (Unauthorized)
• 403 (Forbidden)
• 404 (Not Found)
• 422 (Unprocessable Entity) — write endpoints only

These endpoints do not return 500 or 503 errors in normal operation.

Validation Errors (422)

Iris Detect write endpoints (POST, PUT, and PATCH) return a 422 Unprocessable Entity status code when the request body is syntactically valid JSON but contains values that fail server-side validation. Unlike the standard error format, the 422 response includes per-field validation messages:

{
  "error": {
    "code": 422,
    "summary": "The given data was invalid.",
    "messages": {
      "term": ["The term field is required."],
      "watchlist_domain_ids": ["The watchlist domain ids field is required."]
    }
  },
  "resources": {
    "support": "https://docs.domaintools.com"
  }
}

Common validation triggers include:

• Missing required fields (for example, term when creating a monitor)
• Values that don’t meet minimum length requirements (for example, term must be at least 3 characters)
• Invalid enum values (for example, an unrecognized state value)

This applies to the following endpoints:

Endpoint	Method
/v1/iris-detect/domains/	PATCH
/v1/iris-detect/escalations/	POST
/v1/iris-detect/monitors/	POST
/v1/iris-detect/monitors/	PUT

Iris Enrich and Iris Investigate endpoints do not return 422. These endpoints return 400 for invalid parameters.