Common Errors

Quick reference for troubleshooting common API errors.

Authentication Errors

401 Unauthorized - Missing API Key

Error: 

{
  "error": "Unauthorized",
  "message": "API key required"
}

Cause: No X-API-Key header provided

Solution: 

# ✅ Correct
curl -H "X-API-Key: your-key" https://api.reputeapi.com/api/v1/check?domain=example.com

# ❌ Wrong
curl https://api.reputeapi.com/api/v1/check?domain=example.com

401 Unauthorized - Invalid API Key

Error: 

{
  "error": "Unauthorized",
  "message": "Invalid API key"
}

Causes: - API key is incorrect - API key was revoked - API key expired

Solution: 1. Verify your API key at reputeapi.com/dashboard 2. Generate a new API key if needed 3. Update your environment variables

Rate Limiting Errors

429 Too Many Requests

Error: 

{
  "error": "Rate limit exceeded",
  "retry_after": 60
}

Solution: - Wait for the time specified in retry_after (seconds) - Implement exponential backoff - Use caching to reduce requests - Upgrade your plan for higher limits

See Rate Limits for details.

Validation Errors

400 Bad Request - Invalid Domain

Error: 

{
  "error": "Invalid domain",
  "message": "The domain 'example' is not valid",
  "code": "INVALID_DOMAIN"
}

Common causes: 

# ❌ Missing TLD
check_domain("example")

# ❌ Invalid characters
check_domain("exam ple.com")

# ❌ Protocol included
check_domain("https://example.com")

# ✅ Correct
check_domain("example.com")

400 Bad Request - Invalid DKIM Selector

Error: 

{
  "error": "Invalid DKIM selector",
  "message": "Selector must be alphanumeric"
}

Solution: 

# ❌ Invalid characters
selectors = ["default!", "google@"]

# ✅ Valid selectors
selectors = ["default", "google", "s1"]

DNS Resolution Errors

404 Not Found - Domain Not Found

Error: 

{
  "error": "Resource not found",
  "message": "Domain does not exist or has no DNS records"
}

Causes: - Domain doesn't exist - Domain has no DNS records - Typo in domain name

Solution: 

# Verify domain exists
nslookup example.com

# Check for typos
# ❌ exampel.com (typo)
# ✅ example.com

504 Gateway Timeout - DNS Timeout

Error: 

{
  "error": "DNS timeout",
  "message": "DNS query timed out after 5 seconds"
}

Causes: - DNS servers are slow/unresponsive - Network connectivity issues - Domain's nameservers are down

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

Server Errors

500 Internal Server Error

Error: 

{
  "error": "Internal server error",
  "message": "An unexpected error occurred"
}

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

503 Service Unavailable

Error: 

{
  "error": "Service unavailable",
  "message": "Service is temporarily unavailable"
}

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

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

Content Type Errors

415 Unsupported Media Type

Error: 

{
  "error": "Unsupported media type",
  "message": "Content-Type must be application/json"
}

Solution: 

# ✅ Correct
requests.post(
    url,
    json={"domain": "example.com"},  # Automatically sets Content-Type
    headers={"X-API-Key": API_KEY}
)

# Or explicitly:
requests.post(
    url,
    data='{"domain": "example.com"}',
    headers={
        "X-API-Key": API_KEY,
        "Content-Type": "application/json"
    }
)

Debugging Checklist

When encountering errors:

  1. Check HTTP Status Code
  2. 4xx = Client error (check your request)

  3. 5xx = Server error (retry or contact support)

  4. Read Error Message

  5. Contains specific details about the issue

  6. Look for the code field for error type

  7. Verify API Key 

    echo $REPUTE_API_KEY  # Check it's set

  8. Check Request Format 

    curl -v -H "X-API-Key: $REPUTE_API_KEY" \
  https://api.reputeapi.com/api/v1/check?domain=example.com

  9. Test with Known-Good Domain 

    # Test with google.com (always works)
curl -H "X-API-Key: $REPUTE_API_KEY" \
  "https://api.reputeapi.com/api/v1/check?domain=google.com"

  10. Check Rate Limits 

    # Look for X-RateLimit headers
curl -I -H "X-API-Key: $REPUTE_API_KEY" \
  "https://api.reputeapi.com/api/v1/check?domain=example.com"

Getting Help

Still stuck? We're here to help:

Next Steps