Rate Limits & Tiers

Credit budgets, trust tiers, and how to handle 429 and 402 responses

Rate Limits & Tiers

The Influship API uses credit-based rate limiting. Each request consumes part of your per-minute and per-hour budget based on the credit cost of that operation.

How Limits Work

Two windows are enforced for every API key:

Window	Purpose	Free tier budget
Per minute	Prevent short spikes	150 credits
Per hour	Prevent sustained overuse	1,500 credits

Heavier endpoints use more of that budget than lighter ones. A search with limit: 10 consumes roughly 45 credits of budget, while an autocomplete call consumes 0.05. This means you can make thousands of autocomplete requests in the time it takes to exhaust the budget on a few dozen searches.

See Pricing for the full credit cost table.

Trust Tiers

Trust tiers increase your rate limits as your account matures. They’re based on lifetime spend — not monthly spend — and they never downgrade. A slow month doesn’t reduce your limits.

Tier	Credits/min	Credits/hour	Billing threshold	How to reach
free	150	1,500	$5	Signup
tier_1	750	7,500	$25	First successful payment
tier_2	3,000	30,000	$100	$500 lifetime spend
tier_3	15,000	150,000	$250	$2,000 lifetime spend
enterprise	custom	custom	custom	Contact us

Tiers affect rate limits and billing thresholds only. They do not change endpoint prices — a search costs the same credits on the free tier as on Tier 3.

How Billing Thresholds Work

An invoice is generated when your accumulated usage reaches your tier’s billing threshold. On the free tier, that’s $5. After your first successful payment, you move to Tier 1 and the threshold increases to $25. This means you’re invoiced less frequently as your account matures.

Checking Your Current Tier

Every response includes the X-Billing-Plan header with your current tier code:

X-Billing-Plan: tier_1

Response Headers

Every successful response includes your current rate limit state:

Header	Description
RateLimit-Limit-Minute	Credits allowed in the current minute window
RateLimit-Remaining-Minute	Credits left in the current minute window
RateLimit-Reset-Minute	Unix timestamp when the minute window resets
RateLimit-Limit-Hour	Credits allowed in the current hour window
RateLimit-Remaining-Hour	Credits left in the current hour window
RateLimit-Reset-Hour	Unix timestamp when the hour window resets
X-Billing-Plan	Current trust tier code

Example after a search on the free tier:

RateLimit-Limit-Minute: 150
RateLimit-Remaining-Minute: 105
RateLimit-Reset-Minute: 1703571600
RateLimit-Limit-Hour: 1500
RateLimit-Remaining-Hour: 1455
RateLimit-Reset-Hour: 1703575200
X-Billing-Plan: free

Monitor RateLimit-Remaining-Minute and RateLimit-Remaining-Hour if you’re running batch operations. When either hits zero, the next request gets a 429.

What Happens at the Limit

There’s no warning before you hit a rate limit — the API doesn’t send a “you’re close” signal. When a request would push usage above either the minute or hour budget, it’s rejected with a 429 immediately. The request is not charged.

This means for production integrations, you should track the remaining budget headers proactively rather than waiting for a 429.

429 Rate Limit Exceeded

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded (per minute)",
    "status_code": 429
  }
}

How to handle it:

1. Check the Retry-After header if present — it tells you how many seconds to wait
2. Otherwise, read RateLimit-Reset-Minute or RateLimit-Reset-Hour for the next window
3. Implement exponential backoff: wait 2^attempt seconds, capped at 60s, with jitter
4. If this happens regularly, reduce concurrency or increase your tier

Failed-authentication throttling

Repeated requests with a missing or invalid API key are also throttled. After several failed attempts, subsequent requests return 429 rate_limit_exceeded with the message "Too many failed authentication attempts. Please try again later." and a Retry-After header indicating when the block lifts. This response has no RateLimit-* headers — fix the API key rather than retrying.

503 Is Not Your Account Rate Limit

Live data endpoints can return 503 service_unavailable when an upstream platform temporarily throttles or blocks a live scrape. These responses may include Retry-After plus error.details.retry_after_seconds.

Handle them as retryable temporary upstream failures, but don’t show them to users as “your API key is rate limited.” Your account-level rate limit is always 429 rate_limit_exceeded.

402 Payment Required

{
  "error": {
    "code": "payment_required",
    "message": "Payment required to continue API access",
    "status_code": 402
  }
}

This means billing is suspended — usually because we couldn’t collect payment on your last invoice. Don’t retry 402 automatically; it needs human intervention:

1. Check the dashboard for outstanding invoices
2. Update your payment method if needed
3. Pay the invoice
4. Access resumes immediately after payment

Daily Ingest Quota

On-demand creator ingest (POST /v1/creators/ingest) has a separate per-account daily quota on top of the credit rate limits, because each ingest kicks off background profile building. The default is 50 ingests per UTC day.

Exceeding it returns 429 with error.code: "quota_exceeded" and a Retry-After header pointing to the next UTC midnight. This is distinct from the credit rate_limit_exceeded throttle — it is a volume guard specific to ingest, and like other 429 responses it is not charged.

Ingest itself costs 5 credits ($0.05) and is charged only when a new creator is seeded. See Ingest Creators On Demand for the full flow.

Good Practices

• Monitor your budget headers. Log RateLimit-Remaining-Minute and RateLimit-Remaining-Hour on every response. Set alerts before they hit zero.
• Keep search limit tight. A limit: 25 search consumes 75 credits of your minute budget. Five of those in quick succession can exhaust a free-tier minute window.
• Batch known work. POST /v1/profiles/lookup resolves multiple profiles in one request with minimal rate-limit impact, compared to calling GET /v1/profiles/{platform}/{username} in a loop.
• Treat 429, 503, and 402 differently. 429 is your account throttle — back off and retry. 503 from live data is an upstream/platform throttle — retry later without blaming the user’s key. 402 is a billing issue — surface it to your ops team and stop retrying.
• Budget for the free tier. On the free tier, you can run roughly 3 searches per minute (at limit: 10) or ~33 per hour. That’s enough for prototyping but not for a production integration with real traffic. Upgrade early.