Errors

HTTP status codes and error payloads returned by the Scan API.

Errors are JSON objects with at least error and usually message.

json

{
  "error": "Scan failed",
  "message": "File size exceeds limit: 10MB"
}

Scan and validation

Status	When
`400`	Neither `file` nor `url` was provided
`400`	Empty file, missing filename, invalid URL, oversize payload, ClamAV I/O error
`400`	URL protocol is not `http`/`https`

Typical messages:

Either 'file' or 'url' must be provided
File must not be null or empty
File must have a valid name
File size exceeds limit: 10MB
URL must not be null or blank
URL must start with http or https
Invalid URL format: …
Access to private/local addresses is forbidden
Access to private IP ranges is forbidden

Auth

Status	Body
`401`	`{ "error": "X-API-KEY MISSING" }`
`401`	`{ "error": "X-API-KEY INVALID" }`
`401`	Invalid or expired session JWT on `/web/**`

Quota

Status	When
`429`	Hourly scan limit reached

429

{
  "error": "Rate limit exceeded",
  "message": "...",
  "limit": 5,
  "resetTime": 1710000000,
  "retryAfter": 842
}

Honor Retry-After (seconds) before sending another scan.

Typical malware detected payload is still HTTP 200 — it is not an error:

200 infected

{
  "filename": "payload.exe",
  "extension": "exe",
  "sizeInBytes": 4096,
  "scanDurationMillis": 51,
  "infected": true,
  "virusName": "Win.Test.EICAR_HDB-1"
}

Other

Status	When
`403`	Authenticated but not allowed (billing session mismatch, forbidden resource)
`404`	Unknown user, key, or session
`409`	Email already in use, conflicting billing state
`500`	Unexpected server error (`"error": "Unexpected error"`)
`503`	Billing or a required dependency is not configured

A 400 from the scan stack uses "error": "Scan failed" and puts the human-readable reason in message.

Rate limits

Quota headers and 429 handling for POST /api/v1/scans.