Error Handling

Learn how to handle errors gracefully, interpret error responses, and troubleshoot common issues with the ComplianceLayer API.

Error Response Format

All error responses follow a consistent JSON structure:

{
  "error": "invalid_request",
  "message": "Domain parameter is required",
  "status": 400
}

Field	Type	Description
`error`	string	Machine-readable error code
`message`	string	Human-readable error description
`status`	number	HTTP status code

HTTP Status Codes

200OK

Request succeeded. Response body contains the requested data.

400Bad Request

Invalid request parameters or malformed JSON. Check the error message for details.

{
  "error": "invalid_domain",
  "message": "Domain must be a valid hostname",
  "status": 400
}

401Unauthorized

Missing, invalid, or expired authentication credentials.

{
  "error": "invalid_api_key",
  "message": "The provided API key is invalid or has been revoked",
  "status": 401
}

403Forbidden

Account disabled, subscription inactive, or quota exceeded.

{
  "error": "quota_exceeded",
  "message": "Monthly scan quota exceeded. Upgrade your plan or wait until next billing cycle.",
  "status": 403
}

404Not Found

Resource not found. Check that the ID or endpoint is correct.

{
  "error": "not_found",
  "message": "Scan job not found",
  "status": 404
}

429Too Many Requests

Rate limit exceeded. Wait for the time specified in Retry-After header.

HTTP/1.1 429 Too Many Requests
Retry-After: 45

{
  "error": "rate_limit_exceeded",
  "message": "Rate limit exceeded. Retry in 45 seconds.",
  "status": 429
}

500Internal Server Error

Unexpected server error. Contact support with the request ID from response headers.

{
  "error": "internal_server_error",
  "message": "An unexpected error occurred. Please contact support.",
  "status": 500
}

Common Error Codes

Error Code	Status	Description
`invalid_request`	400	Malformed request or missing required parameters
`invalid_domain`	400	Domain format is invalid
`unauthorized`	401	Missing or invalid authentication
`invalid_api_key`	401	API key is invalid or revoked
`quota_exceeded`	403	Monthly or daily quota exceeded
`account_disabled`	403	Account has been disabled
`not_found`	404	Resource not found
`rate_limit_exceeded`	429	Too many requests

Error Handling Examples

async function scanDomain(domain) {
  try {
    const response = await fetch(
      'https://api.compliancelayer.net/v1/scan',
      {
        method: 'POST',
        headers: {
          'Authorization': `Bearer ${API_KEY}`,
          'Content-Type': 'application/json'
        },
        body: JSON.stringify({ domain })
      }
    );

    if (!response.ok) {
      const error = await response.json();

      switch (response.status) {
        case 400:
          throw new Error(`Invalid request: ${error.message}`);
        case 401:
          throw new Error('Authentication failed. Check your API key.');
        case 403:
          if (error.error === 'quota_exceeded') {
            throw new Error('Monthly quota exceeded. Upgrade your plan.');
          }
          throw new Error(`Forbidden: ${error.message}`);
        case 429:
          const retryAfter = response.headers.get('Retry-After');
          throw new Error(`Rate limited. Retry in ${retryAfter}s`);
        case 500:
          throw new Error('Server error. Please try again later.');
        default:
          throw new Error(`Request failed: ${error.message}`);
      }
    }

    return await response.json();
  } catch (error) {
    console.error('Scan failed:', error.message);
    throw error;
  }
}

Troubleshooting Guide

Domain Resolution Failures

Error: "Domain does not resolve to any IP addresses"

Possible causes:

Domain doesn't exist or DNS is misconfigured
Typo in domain name
Domain was recently registered (DNS not propagated)

Solutions:

Verify domain spelling
Check DNS records with nslookup or dig
Wait 24-48 hours for new domains to propagate

Scan Timeouts

Error: "Scan timed out after 120 seconds"

Possible causes:

Domain is slow to respond
Firewall blocking scan requests
Server overloaded

Solutions:

Retry the scan
Check if domain is accessible publicly
Whitelist ComplianceLayer IP ranges (contact support)

SSL Certificate Errors

Warning: "SSL certificate validation failed"

This is often reported as a finding, not an error. Common issues:

Self-signed certificates
Expired certificates
Hostname mismatch
Incomplete certificate chain

Getting Help

If you're experiencing issues not covered here:

Email: [email protected]
Status Page: status.compliancelayer.net
API Docs: OpenAPI Specification

When contacting support, please include:

Request ID from response headers
Full error message and status code
Example request (with API key redacted)
Timestamp of the error

API Documentation