Errors

Every error response returns a JSON object with an error field describing what went wrong.

{
  "error": "Description of the problem"
}

HTTP status codes

Code	Meaning	When
`400`	Bad Request	Missing or invalid parameters
`401`	Unauthorized	Missing or invalid API key
`402`	Payment Required	Insufficient credit balance
`404`	Not Found	Account not tracked, resource doesn't exist
`409`	Conflict	Resource already exists (e.g., already tracking account)
`429`	Too Many Requests	Rate limit or daily spend cap exceeded
`500`	Internal Error	Server-side issue — retry with backoff

{ "error": "Missing X-API-Key header" }

{ "error": "Invalid or inactive API key" }

Verify your API key is correct and active. Keys can be managed in the Developer Portal (opens in a new tab).

{
  "error": "Insufficient balance",
  "required_cents": 10,
  "balance_cents": 3,
  "top_up": "https://frontrun.vc/api/billing"
}

The response tells you exactly how much is needed vs. available. Top up your balance to continue.

Two types of 429 responses:

Per-minute rate limit:

{
  "error": "API rate limit exceeded. Please slow down.",
  "retry_after_seconds": 60
}

Daily spend cap reached:

{
  "error": "Daily spend cap reached",
  "daily_spent_cents": 5000,
  "daily_cap_cents": 5000,
  "resets_at": "2026-03-12T00:00:00.000Z"
}

The daily spend cap (default $50) prevents runaway agent costs. It resets at midnight UTC.

{ "error": "username is required" }

{ "error": "Invalid \"since\" parameter. Use \"24h\", \"7d\", or \"YYYY-MM-DD\"." }

{
  "error": "At least one filter required: sector, keyword, or entity_type",
  "example": "/v1/search?sector=AI/ML&entity_type=startup"
}

{ "error": "Not tracking @example. Add with POST /v1/track" }

The account must be tracked before you can query follows, convergence, or activity.

{
  "error": "Already tracking this account",
  "baseline_established": true
}

Error	Retry?	Strategy
`400`	No	Fix the request parameters
`401`	No	Check your API key
`402`	No	Top up your balance
`404`	No	Track the account first via `POST /v1/track`
`409`	No	Resource already exists — this is a no-op
`429` (rate limit)	Yes	Wait `retry_after_seconds`, then retry
`429` (spend cap)	Yes	Wait until `resets_at` timestamp
`500`	Yes	Exponential backoff: 1s, 2s, 4s, max 3 retries

Every response includes standard rate limit headers:

Header	Description
`RateLimit-Limit`	Max requests per window
`RateLimit-Remaining`	Requests left in current window
`RateLimit-Reset`	Unix timestamp when the window resets

Check RateLimit-Remaining before making requests to avoid hitting 429s.