Saltar a contenido

Errors, rate limits & versioning

How the API signals failure, enforces quotas, and evolves over time.

Error model

Errors return a standard HTTP status and a JSON body:

{
  "detail": "Human-readable message",
  "code": "quota_exceeded",
  "request_id": "req_01H..."
}

Include the request_id when contacting support — it lets us trace the exact call.

Status codes

Status Meaning Typical cause What to do
400 Bad request Malformed body, invalid target Fix the payload
401 Unauthenticated Missing/expired/revoked token Re-authenticate
403 Forbidden Plan gate, missing role, or unverified domain Upgrade plan, use admin, or complete domain verification
404 Not found Wrong ID or another org's resource Check the ID / org scope
409 Conflict Duplicate or concurrent modification Retry after reconciling
422 Validation error Field-level schema failure Read detail for the field
429 Too many requests Rate limit or daily scan quota exceeded Back off; see headers below
5xx Server error Unexpected failure Retry with backoff; report request_id

Tenant isolation

A resource that belongs to another organization returns 404, not 403 — Vex Raptor does not confirm the existence of resources outside your org.

Rate limits

  • Login is rate-limited per IP/user to slow credential stuffing.
  • Scans are bounded by a per-org daily quota (by plan), enforced atomically. Exceeding it returns 429.
  • Per-target scan traffic is separately rate-capped to keep tests non-disruptive (configurable).

When throttled you receive 429 with headers:

Retry-After: 60
X-RateLimit-Limit: 100
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1720531200

Honor Retry-After; use exponential backoff for 5xx.

Idempotency

GET is safe and idempotent.

Roadmap

Client-supplied Idempotency-Key support for scan-creating calls is planned but not yet implemented — sending the header today has no effect; a retried request starts a new scan. Track this in release notes before relying on it for retry-safety.

Versioning & deprecation

  • The API is versioned in the path: /api/v1.
  • Additive changes (new fields, new endpoints) ship within v1 and are backward-compatible — parse defensively and ignore unknown fields.
  • Breaking changes ship under a new version (/api/v2); the previous version is supported for a documented deprecation window announced in the release notes.
  • The OpenAPI spec at /api/openapi.json is the source of truth for the current contract.