Errors

CortexVigil uses standard HTTP status codes plus a structured JSON body. The body always includes a detail field with a stable machine-readable code.

Response Shape

{
  "detail": "stable_error_code",
  "message": "Human-readable explanation",
  "field_errors": [
    { "loc": ["body", "camera_id"], "msg": "value is not a valid uuid" }
  ]
}

field_errors is only present on 422 validation responses.

Status Codes

400 Bad Request

Malformed request that is not a validation error — e.g., invalid JSON body, mutually exclusive query parameters supplied together. Fix the request and retry.

401 Unauthorized

X-API-Key is missing, malformed, or revoked. The same status is returned for unknown keys (we do not differentiate to avoid leaking which prefixes exist).

{ "detail": "invalid_api_key" }

Fix: verify the key, ensure it has not been revoked in Admin → External Apps, and confirm you are calling the correct environment URL (staging vs production keys are NOT interchangeable).

403 Forbidden

The key is valid but lacks the required scope, OR the resource belongs to a different site than the one the key is bound to.

{ "detail": "insufficient_scope", "required": "write:cameras" }

{ "detail": "cross_site_access_denied" }

Fix: grant the missing scope (rotate the key) or use the correct site's key.

404 Not Found

Resource does not exist OR exists but is not visible to the calling key's site. We intentionally collapse "not found" and "wrong site" into 404 to avoid leaking existence of cross-site resources.

409 Conflict

Resource state conflict — e.g., trying to pair a camera that is already paired, or creating a duplicate area name.

422 Unprocessable Entity

Request body or query parameters failed schema validation. field_errors lists each failure. Do not retry without changes.

429 Too Many Requests

Rate limit exceeded. See Rate Limits. Respect the Retry-After header.

5xx Server Errors

Every 5xx response includes an X-Request-Id header — quote this when filing support tickets so we can trace the request through our logs.

Idempotency

POST operations that create resources accept an optional Idempotency-Key request header (UUIDv4 recommended). Retrying with the same key within 24h returns the original response without creating a duplicate.