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

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 based on lifetime spend. Once you reach a tier, you keep its limits regardless of monthly usage.

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

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

Track your remaining budget through the response headers. A request that would exceed either the minute or hour budget returns `429` and 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,
    "reason_code": "PAYMENT_FAILED",
    "next_step": "update_payment_method"
  }
}
```

Use `reason_code` for the specific billing or subscription state and `next_step` for the recovery action. Don't retry 402 automatically.

Search can return a different 402 body when remaining credits cannot cover the request:

```json theme={null}
{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits remaining for this search. Add a payment method to continue.",
    "details": {
      "remaining": 10,
      "required": 75,
      "add_payment_method": true
    }
  }
}
```

That shape has no `reason_code` or `next_step`. Add a payment method and retry; do not treat it as a transient failure.

For `payment_required`:

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

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

A slot is only consumed when the ingest request is accepted. Handles that do not exist (`404`) or cannot be validated right now (`503 service_unavailable`) do not count against the quota.

Ingest costs **5 credits (\$0.05)** when a new creator is accepted for enrichment. See [Ingest Creators On Demand](/guides/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.
* **Plan for your request volume.** At `limit: 10`, the free-tier budgets cover roughly 3 searches per minute or 33 per hour. Compare your expected traffic with the tier table above.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.