> ## Documentation Index
> Fetch the complete documentation index at: https://docs.influship.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Rate Limits & Tiers

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

# Rate Limits & Tiers

The Influship API uses <Tooltip tip="Credits are the billing unit for API usage. 1 credit = \$0.01.">credit</Tooltip>-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.

<Info>
  See [Pricing](/concepts/pricing) for the full credit cost table.
</Info>

## Trust Tiers

<Tooltip tip="Trust tiers are based on lifetime spend and determine your rate limit budgets and billing thresholds.">Trust tiers</Tooltip> 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](mailto:elliot@influship.com) |

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:

```http theme={null}
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:

```http theme={null}
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

```json theme={null}
{
  "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

```json theme={null}
{
  "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](https://developers.influship.com) for outstanding invoices
2. Update your payment method if needed
3. Pay the invoice
4. Access resumes immediately after payment

## 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.