Error Codes¶

Complete reference for all error codes returned by the API.

Overview¶

All errors follow a consistent JSON structure:

{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "details": {
      "field": "additional context"
    }
  },
  "request_id": "req_abc123"
}

Error Response Structure¶

HTTP Status Codes¶

400 Bad Request Errors¶

INVALID_DOMAIN¶

Cause: Domain format is invalid

Example:

{
  "error": {
    "code": "INVALID_DOMAIN",
    "message": "Invalid domain format: example",
    "details": {
      "domain": "example"
    }
  }
}

Common Causes: - Missing top-level domain (TLD) - Invalid characters in domain name - Protocol prefix included (http://, https://) - Whitespace in domain

Solution:

# Invalid
curl "https://api.reputeapi.com/api/v1/check?domain=example"
curl "https://api.reputeapi.com/api/v1/check?domain=https://example.com"

# Valid
curl "https://api.reputeapi.com/api/v1/check?domain=example.com"

INVALID_SELECTOR¶

Cause: DKIM selector contains invalid characters

Example:

{
  "error": {
    "code": "INVALID_SELECTOR",
    "message": "Invalid DKIM selector: default!",
    "details": {
      "selector": "default!"
    }
  }
}

Common Causes: - Special characters (!, @, #, etc.) - Whitespace in selector - Empty selector string

Solution:

# Invalid
curl "https://api.reputeapi.com/api/v1/check?domain=example.com&selectors=default!,google@"

# Valid - alphanumeric and hyphens only
curl "https://api.reputeapi.com/api/v1/check?domain=example.com&selectors=default,google,s1"

INVALID_EMAIL¶

Cause: Email address format is invalid

Example:

{
  "error": {
    "code": "INVALID_EMAIL",
    "message": "Invalid email format: user@",
    "details": {
      "email": "user@"
    }
  }
}

Solution: Ensure email follows standard format: user@domain.com

VALIDATION_ERROR¶

Cause: Generic validation failure

Example:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed",
    "details": {
      "errors": [
        {
          "field": "domain",
          "message": "field required",
          "type": "value_error.missing"
        }
      ]
    }
  }
}

Solution: Check all required parameters are provided and properly formatted

401 Unauthorized Errors¶

AUTHENTICATION_FAILED¶

Cause: General authentication failure

Example:

{
  "error": {
    "code": "AUTHENTICATION_FAILED",
    "message": "Authentication failed"
  }
}

INVALID_API_KEY¶

Cause: API key is missing, malformed, or not found

Example:

{
  "error": {
    "code": "INVALID_API_KEY",
    "message": "Invalid or missing API key"
  }
}

Common Causes: - No X-API-Key header provided - API key format is incorrect - API key does not exist in system

Solution:

# Missing API key
curl "https://api.reputeapi.com/api/v1/check?domain=example.com"

# Valid - include X-API-Key header
curl -H "X-API-Key: your-api-key-here" \
  "https://api.reputeapi.com/api/v1/check?domain=example.com"

EXPIRED_API_KEY¶

Cause: API key has passed its expiration date

Example:

{
  "error": {
    "code": "EXPIRED_API_KEY",
    "message": "API key has expired"
  }
}

Solution: Generate a new API key at reputeapi.com/dashboard

403 Forbidden Errors¶

INACTIVE_API_KEY¶

Cause: API key is disabled or revoked

Example:

{
  "error": {
    "code": "INACTIVE_API_KEY",
    "message": "API key is inactive or revoked"
  }
}

Solution: Check your dashboard - key may have been revoked. Generate a new key if needed.

INSUFFICIENT_PERMISSIONS¶

Cause: API key lacks required permissions for this operation

Example:

{
  "error": {
    "code": "INSUFFICIENT_PERMISSIONS",
    "message": "Insufficient permissions"
  }
}

Solution: Contact support or upgrade your plan if you need access to this endpoint

404 Not Found Errors¶

RESOURCE_NOT_FOUND¶

Cause: Requested resource does not exist

Example:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Historical data not found: example.com",
    "details": {
      "resource_type": "Historical data",
      "resource_id": "example.com"
    }
  }
}

Common Scenarios: - No history exists for domain - Domain has never been checked - Invalid endpoint path

Solution: Verify resource exists before accessing it

DNS_RECORD_NOT_FOUND¶

Cause: DNS record does not exist for domain

Example:

{
  "error": {
    "code": "DNS_RECORD_NOT_FOUND",
    "message": "No TXT record found for example.com",
    "details": {
      "domain": "example.com",
      "record_type": "TXT"
    }
  }
}

Common Causes: - Domain has no DNS records configured - Domain does not exist - Typo in domain name

Solution: Verify domain exists and has DNS records configured

422 Unprocessable Entity¶

Request Validation Failed¶

Cause: Request body failed schema validation

Example:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Request validation failed",
    "details": {
      "errors": [
        {
          "field": "body.domain",
          "message": "ensure this value has at least 4 characters",
          "type": "value_error.any_str.min_length"
        }
      ]
    }
  }
}

Solution: Check request body matches the expected schema

429 Rate Limit Errors¶

RATE_LIMIT_EXCEEDED¶

Cause: Too many requests in time window

Example:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded",
    "details": {
      "limit_type": "per_minute",
      "limit": 60
    }
  }
}

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1698765432
Retry-After: 30

Solution: - Wait for time specified in Retry-After header (seconds) - Implement exponential backoff - Use caching to reduce requests - Upgrade plan for higher limits

Example with retry:

import time
import requests

response = requests.get(url, headers=headers)

if response.status_code == 429:
    retry_after = int(response.headers.get('Retry-After', 60))
    print(f"Rate limited. Retrying after {retry_after} seconds...")
    time.sleep(retry_after)
    response = requests.get(url, headers=headers)

MONTHLY_QUOTA_EXCEEDED¶

Cause: Monthly API call quota exhausted

Example:

{
  "error": {
    "code": "MONTHLY_QUOTA_EXCEEDED",
    "message": "Monthly quota exceeded",
    "details": {
      "limit_type": "monthly",
      "limit": 10000
    }
  }
}

Solution: - Wait until quota resets (first of next month) - Upgrade to higher tier plan - Contact sales for quota increase

500 Internal Server Error¶

INTERNAL_SERVER_ERROR¶

Cause: Unexpected server error

Example:

{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "An internal error occurred"
  }
}

Solution: - Retry the request (may be temporary) - Check status page - Contact support with request_id if persists

DATABASE_ERROR¶

Cause: Database operation failed

Example:

{
  "error": {
    "code": "DATABASE_ERROR",
    "message": "A database error occurred. Please try again later."
  }
}

Solution: Retry after a few seconds. Contact support if error persists.

CACHE_ERROR¶

Cause: Cache operation failed

Example:

{
  "error": {
    "code": "CACHE_ERROR",
    "message": "A cache error occurred. Please try again later."
  }
}

Solution: Request will still work but may be slower. Retry if needed.

CONFIGURATION_ERROR¶

Cause: Server misconfiguration

Example:

{
  "error": {
    "code": "CONFIGURATION_ERROR",
    "message": "Configuration error"
  }
}

Solution: This indicates a server-side issue. Contact support immediately.

502 Bad Gateway Errors¶

DNS_ERROR¶

Cause: DNS lookup failed

Example:

{
  "error": {
    "code": "DNS_ERROR",
    "message": "DNS lookup failed"
  }
}

Common Causes: - DNS servers unresponsive - Invalid DNS configuration - Network connectivity issues

Solution: Retry request. If persists, check domain's DNS configuration.

DNS_RESOLUTION_FAILED¶

Cause: Unable to resolve domain

Example:

{
  "error": {
    "code": "DNS_RESOLUTION_FAILED",
    "message": "Failed to resolve example.com: NXDOMAIN",
    "details": {
      "domain": "example.com",
      "reason": "NXDOMAIN"
    }
  }
}

Solution: Verify domain name is correct and domain exists

503 Service Unavailable¶

SERVICE_UNAVAILABLE¶

Cause: Service temporarily unavailable

Example:

{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service unavailable: dns_resolver",
    "details": {
      "service_name": "dns_resolver"
    }
  }
}

Common Causes: - Scheduled maintenance - System upgrade in progress - Temporary overload

Solution: - Wait a few minutes and retry - Check status page - Implement retry logic with exponential backoff

DATABASE_CONNECTION_FAILED¶

Cause: Cannot connect to database

Example:

{
  "error": {
    "code": "DATABASE_CONNECTION_FAILED",
    "message": "Failed to connect to database"
  }
}

Solution: Temporary issue. Retry after a few seconds.

CACHE_CONNECTION_FAILED¶

Cause: Cannot connect to cache service

Example:

{
  "error": {
    "code": "CACHE_CONNECTION_FAILED",
    "message": "Failed to connect to cache"
  }
}

Solution: API will function but may be slower. Retry if needed.

NETWORK_ERROR¶

Cause: Network operation failed

Example:

{
  "error": {
    "code": "NETWORK_ERROR",
    "message": "Network error occurred"
  }
}

Solution: Temporary connectivity issue. Retry request.

504 Gateway Timeout¶

DNS_TIMEOUT¶

Cause: DNS query exceeded timeout limit

Example:

{
  "error": {
    "code": "DNS_TIMEOUT",
    "message": "DNS lookup timed out for example.com after 5.0s",
    "details": {
      "domain": "example.com",
      "timeout": 5.0
    }
  }
}

Common Causes: - Domain's nameservers are slow/down - Network latency - DNS server overload

Solution: - Retry the request - Check domain's nameservers: dig +trace example.com - Verify domain resolves: dig example.com

Error Handling Best Practices¶

1. Check Status Code First¶

if response.status_code == 200:
    # Success
    data = response.json()
elif response.status_code >= 400 and response.status_code < 500:
    # Client error - check your request
    error = response.json()
    print(f"Client error: {error['error']['code']}")
elif response.status_code >= 500:
    # Server error - retry
    print("Server error, retrying...")

2. Parse Error Response¶

try:
    data = response.json()
    error_code = data['error']['code']
    error_message = data['error']['message']
    details = data['error'].get('details', {})
    request_id = data.get('request_id')

    print(f"Error {error_code}: {error_message}")
    print(f"Request ID: {request_id}")
except KeyError:
    print(f"HTTP {response.status_code}: {response.text}")

3. Implement Retry Logic¶

import time

def make_request_with_retry(url, max_retries=3):
    for attempt in range(max_retries):
        response = requests.get(url, headers=headers)

        if response.status_code == 200:
            return response.json()

        if response.status_code == 429:
            # Rate limited - respect Retry-After
            retry_after = int(response.headers.get('Retry-After', 60))
            time.sleep(retry_after)
            continue

        if response.status_code >= 500:
            # Server error - exponential backoff
            wait_time = 2 ** attempt
            time.sleep(wait_time)
            continue

        # Client error - don't retry
        response.raise_for_status()

    raise Exception(f"Failed after {max_retries} retries")

4. Log Request IDs¶

Always log the request_id when errors occur. This helps support troubleshoot issues:

error = response.json()
request_id = error.get('request_id')
logger.error(f"API error: {error['error']['code']} (request_id: {request_id})")

Getting Help¶

If you encounter persistent errors:

1. Check Status Page: status.reputeapi.com
2. Review Documentation: docs.reputeapi.com
3. Contact Support: support@reputeapi.com
4. Include the request_id from error response
5. Describe what you were trying to do
6. Share relevant code snippets

Related Documentation¶

• Response Format - Standard response structure
• Rate Limits - Rate limiting details
• Common Errors - Quick troubleshooting guide
• Authentication - API key setup