Errors & Status Codes

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

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

HTTP status codes

Error responses by type

401 - Authentication

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

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

{ "error": "API key expired" }

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

402 - Insufficient credits

{
  "error": "Insufficient credits",
  "required_credits": 60,
  "balance_credits": 12,
  "monthly_credits": 0,
  "topup_credits": 12,
  "tier": "pro",
  "top_up": "https://frontrun.vc/api/billing"
}

The response tells you exactly how many credits are needed vs. available - monthly_credits and topup_credits show where your remaining balance comes from. Top up (or enable auto-refill) to continue.

429 - Rate limited

Two types of 429 responses:

Per-minute rate limit:

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

Daily credit cap reached:

{
  "error": "Daily credit cap reached",
  "daily_spent_credits": 80000,
  "daily_cap_credits": 80000,
  "tier": "pro",
  "resets_at": "2026-03-12T00:00:00.000Z"
}

The daily credit cap (80,000 credits/day on Pro) prevents runaway agent costs. It resets at midnight UTC.

400 - Invalid parameters

{ "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"
}

Errors from the agent-oriented parameters carry an error_code so they can be branched on without string matching. See Budgets & Cursors.

max_credits_exceeded - the call could cost more than the ceiling you set. It fails closed: no work ran and nothing was charged. Retry with a smaller limit, fewer include sections, or a higher ceiling.

{
  "error": "This call could cost up to 1624 credits, which is above your max_credits of 200. Nothing was charged and no work was done.",
  "error_code": "max_credits_exceeded",
  "max_cost_credits": 1624,
  "max_credits": 200,
  "charged_credits": 0,
  "hint": "Classification is 16 credits per entity returned. Lower limit (currently 100), drop classify=true, or raise max_credits."
}

invalid_cursor - the cursor was modified, or is being replayed against a different endpoint, API key, or filter set. Cursors are opaque and scoped; mint a fresh one with since.

{
  "error": "This cursor was issued for a different endpoint, API key, or filter set. Cursors are scoped; start a fresh run with since when you change filters.",
  "error_code": "invalid_cursor"
}

invalid_include - an unknown section name was passed to GET /v1/company/:handle?include=. Allowed: resources, founders, funding.

batch_too_large - more items than the endpoint's batch ceiling. The response carries max_batch_size and received.

{
  "error": "Max 50 usernames per request. Split the list and call again.",
  "error_code": "batch_too_large",
  "max_batch_size": 50,
  "received": 150
}

403 - Tier limit

Returned when an action would exceed your subscription tier's quota. Currently used by POST /v1/track when you've reached the tracked-account limit for your tier.

{
  "error": "You have reached your limit of 25 tracked accounts. Please upgrade your plan to track more.",
  "code": "TRACKED_ACCOUNT_LIMIT",
  "tier": "free"
}

Upgrade your subscription or untrack existing accounts (DELETE /v1/track/:username) before adding new ones.

404 - Not found

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

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

409 - Already exists

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

503 - Upstream unavailable

Returned by the handle-lookup endpoints (/v1/preview/:h, /v1/company/:h, /v1/company/:h/signals, /v1/company/:h/resources, /v1/company/:h/funding, /v1/company/:h/founders, /v1/track) when the upstream X/Twitter data provider is slow or temporarily unreachable.

{
  "error": "Twitter upstream temporarily unavailable. Please retry.",
  "retry_after_seconds": 30
}

The response includes a Retry-After: 30 HTTP header. Back off for the indicated interval and retry - these are transient and usually clear within a minute.

Retry guidance