API Error Codes

Common Causes

• X-API-Key header not included in request
• API key format incorrect (must start with vx_live_ or vx_test_)
• API key does not exist in database
• API key has been revoked

Resolution Steps

1. Verify X-API-Key header is present in all requests
2. Check API key format matches vx_live_* or vx_test_* pattern (legacy sk_* keys are still accepted)
3. Generate new API key from dashboard (/dashboard/api-keys)
4. Confirm key hasn't been revoked or deleted

Example

curl -X POST https://vertaaux.ai/v1/audit \
  -H "Content-Type: application/json" \
  -d '{"url":"https://example.com"}'

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

Common Causes

• Key revoked via dashboard
• Key compromised and auto-revoked
• Account security incident

Resolution Steps

1. Generate a new API key from dashboard
2. Review account security settings
3. Contact support if revocation was unexpected

Example

{
  "error": "api_key_revoked",
  "message": "This API key has been revoked. Generate a new key from your dashboard.",
  "details": {
    "revoked_at": "2025-01-10T12:30:00Z"
  }
}

Common Causes

• Attempting to access another user's audit
• Attempting to modify resources you don't own
• IP not whitelisted (Enterprise feature)

Resolution Steps

1. Verify you're using the correct job_id for your account
2. Check resource ownership in dashboard
3. Contact admin to update IP whitelist (Enterprise only)

Example

{
  "error": "forbidden",
  "message": "You do not have permission to access this resource"
}

Common Causes

• Attempting to use deep mode on Free tier
• Requesting > 5 pages on Pro tier
• Using webhooks on Free tier

Resolution Steps

1. Upgrade plan from /pricing
2. Use basic mode or reduce page count
3. Review tier limits at /developer-docs#rate-limiting

Example

POST /v1/audit
{
  "url": "https://example.com",
  "mode": "deep",
  "max_pages": 10
}

{
  "error": "tier_restriction",
  "message": "Deep mode requires Pro or Enterprise plan",
  "details": {
    "current_tier": "free",
    "required_tier": "pro",
    "upgrade_url": "https://vertaaux.ai/pricing"
  }
}

Common Causes

• JSON syntax error in request body
• Missing Content-Type: application/json header
• Invalid field types (e.g., string instead of number)

Resolution Steps

1. Validate JSON syntax before sending
2. Include Content-Type: application/json header
3. Check field types match OpenAPI spec

Example

POST /v1/audit
{
  "url": "https://example.com",
  "mode": "basic",
  "max_pages": "five"  // Should be number
}

{
  "error": "invalid_request",
  "message": "Invalid field type",
  "details": {
    "field": "max_pages",
    "expected": "number",
    "received": "string"
  }
}

Common Causes

• URL missing http:// or https:// scheme
• Malformed domain name
• Internal IP addresses (localhost, 127.0.0.1, 10.x.x.x)
• URL contains invalid characters

Resolution Steps

1. Ensure URL starts with https:// or http://
2. Test URL in browser first
3. Use publicly accessible URLs only
4. URL-encode special characters

Example

POST /v1/audit
{
  "url": "example.com",  // Missing scheme
  "mode": "basic"
}

{
  "error": "invalid_url",
  "message": "Invalid URL format. Must be a valid HTTP or HTTPS URL.",
  "details": {
    "field": "url",
    "value": "example.com",
    "hint": "Did you mean https://example.com?"
  }
}

Common Causes

• Mode field contains unsupported value
• Typo in mode name
• Mode field missing (should default to 'basic')

Resolution Steps

1. Use mode: 'basic' for single-page audits
2. Use mode: 'deep' for multi-page crawling (Pro+)
3. Check spelling matches exactly: 'basic' or 'deep'

Example

POST /v1/audit
{
  "url": "https://example.com",
  "mode": "standard"  // Invalid
}

{
  "error": "invalid_mode",
  "message": "Mode must be 'basic' or 'deep'",
  "details": {
    "field": "mode",
    "value": "standard",
    "allowed_values": ["basic", "deep"]
  }
}

Common Causes

• URL field not provided in POST /audit
• Webhook secret missing in POST /webhooks
• Required query parameter omitted

Resolution Steps

1. Check OpenAPI spec for required fields
2. Include all required parameters in request
3. Verify field names match documentation exactly

Example

POST /v1/audit
{
  "mode": "basic"
  // Missing 'url' field
}

{
  "error": "missing_parameter",
  "message": "Required parameter missing",
  "details": {
    "field": "url",
    "location": "body"
  }
}

Common Causes

• Free tier: max_pages > 1
• Pro tier: max_pages > 5
• Enterprise tier: max_pages > 20

Resolution Steps

1. Reduce max_pages to your tier limit
2. Upgrade plan for higher limits
3. Split audit into multiple requests

Example

POST /v1/audit
{
  "url": "https://example.com",
  "mode": "deep",
  "max_pages": 50
}

{
  "error": "page_limit_exceeded",
  "message": "max_pages exceeds tier limit",
  "details": {
    "requested": 50,
    "max_allowed": 5,
    "current_tier": "pro"
  }
}

Common Causes

• Free: >3 audits per day
• Pro: >1000 audits per month
• Enterprise: Custom limit exceeded
• Burst limit exceeded (too many concurrent requests)

Resolution Steps

1. Wait until quota reset time (see X-RateLimit-Reset header)
2. Implement exponential backoff
3. Upgrade plan for higher limits
4. Distribute requests over time instead of bursting

Example

{
  "error": "rate_limit_exceeded",
  "message": "Daily audit quota exceeded. Resets at midnight UTC.",
  "details": {
    "limit": 3,
    "reset_at": "2025-01-11T00:00:00Z"
  }
}

Headers:
X-RateLimit-Limit: 3
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1736553600
Retry-After: 43200

Common Causes

• Sending multiple audit requests simultaneously
• Polling status too aggressively (< 1 second intervals)

Resolution Steps

1. Limit concurrency to 2 requests per account
2. Use webhooks instead of polling
3. Add delays between requests (minimum 1 second)
4. Implement request queue on client side

Example

{
  "error": "concurrent_limit_exceeded",
  "message": "Maximum 2 concurrent requests allowed. Please queue subsequent requests.",
  "details": {
    "current_requests": 3,
    "max_allowed": 2
  }
}

Common Causes

• Job ID does not exist
• Job belongs to different account
• Webhook ID invalid or deleted
• Endpoint path typo

Resolution Steps

1. Verify job_id matches response from POST /audit
2. Check you're using correct API key for the audit
3. Confirm resource hasn't been deleted
4. Review endpoint path in documentation

Example

GET /v1/audit/invalid_job_id

{
  "error": "not_found",
  "message": "Audit job not found",
  "details": {
    "job_id": "invalid_job_id"
  }
}

Common Causes

• Database connection failure
• Unhandled exception in audit engine
• Infrastructure issue

Resolution Steps

1. Retry request after brief delay (5-10 seconds)
2. Check status page (/status) for incidents
3. Contact support if error persists
4. Include job_id and timestamp in support ticket

Example

{
  "error": "internal_error",
  "message": "An unexpected error occurred. Our team has been notified.",
  "details": {
    "trace_id": "abc123xyz789",
    "timestamp": "2025-01-10T15:30:00Z"
  }
}

Common Causes

• Target website extremely slow (>30 seconds)
• Network connectivity issues
• Website blocking automated access
• Large page with many resources

Resolution Steps

1. Verify URL loads in browser within 30 seconds
2. Use mode: 'basic' for faster results
3. Contact support if legitimate site fails consistently
4. Check website isn&apos;t behind authentication

Example

{
  "error": "timeout",
  "message": "Page load exceeded 30 second timeout",
  "details": {
    "url": "https://very-slow-site.com",
    "timeout_seconds": 30
  }
}

Common Causes

• Engine maintenance in progress
• High load causing temporary unavailability
• Infrastructure scaling event

Resolution Steps

1. Retry after 30-60 seconds
2. Check status page for maintenance notices
3. Subscribe to status updates at /status

Example

{
  "error": "engine_failure",
  "message": "Audit engine temporarily unavailable. Please retry.",
  "details": {
    "retry_after_seconds": 60
  }
}

Headers:
Retry-After: 60