Error Reference

This page documents every error the Cert-IX Scan API can return, organized by category. Use this as a reference when debugging integration issues.

Response Format

All error responses follow a consistent JSON envelope:

{
  "success": false,
  "error": "Human-readable error description",
  "code": "MACHINE_READABLE_CODE"
}

Field	Description
success	Always false for errors
error	Descriptive message explaining the problem
code	Stable machine-readable error code for programmatic handling

HTTP Status Codes

Status	Category	Meaning
400	Client Error	Invalid request — malformed JSON, missing required fields, invalid parameters
401	Authentication	Missing, invalid, expired, or revoked API key
403	Authorization	Valid key but insufficient scope, IP not allowed, or scan type not permitted
404	Not Found	Resource does not exist or does not belong to your tenant
409	Conflict	Resource state conflict (e.g., cancelling an already completed scan)
429	Rate Limit	Rate limit or quota exceeded
500	Server Error	Internal server error — contact support if persistent
503	Unavailable	Service temporarily unavailable — retry with backoff

Authentication Errors (401)

Code	Message	Cause	Resolution
MISSING_API_KEY	API key is required	No X-API-Key header provided	Add the X-API-Key header to your request
INVALID_API_KEY	Invalid API key	Key format is incorrect or doesn't exist	Verify the key format starts with cix_sk_
KEY_EXPIRED	API key has expired	Key has passed its expiresAt date	Create a new key or rotate the expired one
KEY_REVOKED	API key has been revoked	Key was explicitly revoked	Create a new key
KEY_SUSPENDED	API key has been suspended	Key was suspended by an admin	Contact your organization admin

Authorization Errors (403)

Code	Message	Cause	Resolution
INSUFFICIENT_SCOPE	Insufficient scope: requires {scope}	Key lacks the required scope for this operation	Create a new key with the required scope
SCAN_TYPE_NOT_ALLOWED	Scan type {type} not allowed for this API key	Key's allowedScanTypes doesn't include this engine	Update the key or create one with this scan type allowed
IP_NOT_ALLOWED	Source IP not in allowed list	Request IP is not in the key's allowedIpAddresses	Add the source IP to the key's allowlist or remove IP restrictions
TENANT_SUSPENDED	Tenant account is suspended	Your organization's account has been suspended	Contact [email protected]

Scan Errors (400 / 404 / 409)

Code	HTTP	Message	Resolution
SCAN_NOT_FOUND	404	Scan not found	Verify the scan ID and scanType parameter
INVALID_SCAN_TYPE	400	Invalid scan type: {type}	Use a valid engine: nmap, zap, trivy, nuclei, nikto, sqlmap, wapiti, harvester, sublist3r, sentinel
INVALID_TARGET	400	Invalid target format	Check the target matches the expected format for the scan type
INVALID_PRIORITY	400	Invalid priority: {value}	Use: critical, high, normal, or low
SCAN_ALREADY_COMPLETED	409	Scan has already completed	Cannot cancel a scan that has reached a terminal state
SCAN_ALREADY_CANCELLED	409	Scan has already been cancelled	Scan was already cancelled
SCAN_ALREADY_FAILED	409	Scan has already failed	Cannot cancel a scan that has failed
RESULTS_NOT_READY	409	Scan results are not yet available	Wait for the scan to reach completed status

Template Errors (400 / 404)

Code	HTTP	Message	Resolution
TEMPLATE_NOT_FOUND	404	Scan template not found	Verify the template ID
TEMPLATE_NAME_REQUIRED	400	Template name is required	Provide a name field
DUPLICATE_TEMPLATE_NAME	400	Template name already exists	Use a unique name

Webhook Errors (400 / 404)

Code	HTTP	Message	Resolution
WEBHOOK_NOT_FOUND	404	Webhook not found	Verify the webhook ID
INVALID_WEBHOOK_URL	400	Webhook URL must use HTTPS	Ensure your URL starts with https://
WEBHOOK_URL_UNREACHABLE	400	Could not reach webhook URL	Verify your endpoint is publicly accessible
INVALID_WEBHOOK_EVENT	400	Invalid event type: {event}	Use valid events: scan.completed, scan.failed, scan.started, scan.cancelled
WEBHOOK_DISABLED	409	Webhook is disabled due to consecutive failures	Re-enable with PATCH and fix your endpoint

Rate Limit & Quota Errors (429)

Code	Message	Resolution
RATE_LIMIT_EXCEEDED	Rate limit exceeded. Retry in {N} seconds.	Implement exponential backoff; check Retry-After header
QUOTA_EXCEEDED	Monthly scan quota exceeded	Upgrade your plan or wait for the next billing period

Validation Errors (400)

Code	Message	Resolution
INVALID_JSON	Request body is not valid JSON	Check your JSON syntax
MISSING_REQUIRED_FIELD	Missing required field: {field}	Include all required fields
INVALID_FIELD_TYPE	Field {field} must be of type {type}	Correct the field data type
INVALID_PAGE	Page must be a positive integer	Use page ≥ 1
INVALID_LIMIT	Limit must be between 1 and 100	Use limit between 1 and 100

Server Errors (500 / 503)

Code	Message	Resolution
INTERNAL_ERROR	An internal server error occurred	Retry with backoff; contact support if persistent
SERVICE_UNAVAILABLE	Service temporarily unavailable	Retry with backoff; check status.cert-ix.com
DATABASE_ERROR	Database operation failed	Retry; contact support if persistent
KAFKA_ERROR	Message queue operation failed	Retry; the scan queue may be temporarily congested

Troubleshooting Guide

"401 — MISSING_API_KEY"

Check: Are you passing the X-API-Key header?

# ✅ Correct
curl -H "X-API-Key: cix_sk_..." https://api.cert-ix.com/scan-api/api/v1/scans

# ❌ Wrong — key in URL params
curl "https://api.cert-ix.com/scan-api/api/v1/scans?apiKey=cix_sk_..."

# ❌ Wrong — using Authorization header
curl -H "Authorization: Bearer cix_sk_..." https://api.cert-ix.com/scan-api/api/v1/scans

"403 — INSUFFICIENT_SCOPE"

Your key doesn't have the required scope. Check which scope is needed in the error message, then create a new key or update the existing one with the required scope.

"404 — SCAN_NOT_FOUND"

Most common causes:

1. Wrong scanType — If you created a zap scan, you must query with ?scanType=zap
2. Wrong scan ID — Double-check the UUID
3. Different tenant — Keys from different organizations can't see each other's scans

"429 — RATE_LIMIT_EXCEEDED"

Implement exponential backoff:

import time

def request_with_backoff(func, max_retries=5):
    for attempt in range(max_retries):
        response = func()
        if response.status_code != 429:
            return response
        retry_after = int(response.headers.get("Retry-After", 2 ** attempt))
        print(f"Rate limited. Retrying in {retry_after}s...")
        time.sleep(retry_after)
    raise Exception("Max retries exceeded")

"429 — QUOTA_EXCEEDED"

Options:

1. Upgrade your plan for a higher quota
2. Wait until the next billing period (1st of the month, midnight UTC)
3. Optimize — Reduce unnecessary scans or use templates with narrower scan options

"500 — INTERNAL_ERROR"

1. Retry — Most 500 errors are transient
2. Check status.cert-ix.com for outage information
3. Contact [email protected] with the request ID from the error response

---

Next Steps:

• Code Examples →
• Getting Started →
• Authentication →