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

# Quotas & Plans

> Understanding credit quotas and plan limits

## How Quotas Work

Fetchin uses a quota system to track your API usage. Each API request consumes one credit from your quota. The one exception is [`/post/engagement`](/api-reference/endpoint/get-post-engagement), which returns comments and reactions together and bills **2 credits** (all-or-nothing: 0 credits if the request errors).

### Credit Counting

* ✅ **Successful requests** - Count toward your credits
* ✅ **Failed requests** (4xx, 5xx errors) - Do NOT count toward your credits
* 🔄 **Quota renewal** - Happens automatically on your renewal date

<Info>
  Only successful requests count toward your quota. Failed requests (authentication errors, validation errors, server errors, etc.) are free and do not consume credits.
</Info>

## Available Plans

<CardGroup cols={2}>
  <Card title="Trial Plan" icon="gift">
    **1,000 credits/month**

    Perfect for testing and small projects

    * Auto-created on signup
    * 5 requests per second (RPS)
    * Renews monthly
    * Free forever
  </Card>

  <Card title="Enterprise Plan" icon="building">
    **Custom limits**

    For production workloads

    * Custom monthly credit limits
    * Custom RPS limits
    * Priority support
    * Volume discounts
    * Contact sales
  </Card>
</CardGroup>

## Monitoring Your Quota

### Dashboard

Your dashboard shows real-time quota information:

* **Credits Remaining** - How many credits you have left
* **Plan Limit** - Your monthly quota
* **RPS Limit** - Your requests per second limit
* **Renewal Date** - When your quota will reset
* **Usage Chart** - Daily breakdown of your usage

### Checking Quota Programmatically

Currently, quota information is only available through the dashboard. API endpoint for quota checking coming soon!

## Quota Management

### What Happens When You Run Out?

When your quota reaches 0, API requests return a `402 Payment Required` error
with `code: "QUOTA_EXHAUSTED"`. This is distinct from a `429 Too Many Requests`
(`code: "RATE_LIMITED"`), which is per-second throttling — the HTTP status alone
tells them apart:

```json theme={null}
{
  "error": "Quota exceeded. Upgrade your plan or wait for renewal.",
  "code": "QUOTA_EXHAUSTED"
}
```

### Options When Quota Is Exceeded

<Steps>
  <Step title="Wait for renewal">
    Your quota automatically resets on your renewal date (shown in dashboard)
  </Step>

  <Step title="Upgrade your plan">
    Contact sales for an Enterprise plan with higher limits
  </Step>

  <Step title="Purchase overage">
    Coming soon - buy additional credits without upgrading
  </Step>
</Steps>

## Future: Overage Billing

We're working on overage billing that will let you:

* Automatically purchase additional credits when quota is low
* Pay per credit for usage beyond your plan
* Never get blocked by quota limits
* Set spending caps for cost control

<Note>
  Interested in overage billing? Contact support to join the waitlist.
</Note>

## Best Practices

<AccordionGroup>
  <Accordion title="Cache results when possible">
    Store API responses locally to avoid redundant requests for the same data.
  </Accordion>

  <Accordion title="Implement retry logic with backoff">
    Use exponential backoff for failed requests instead of immediately retrying.
  </Accordion>

  <Accordion title="Monitor your usage">
    Check your dashboard regularly to track usage patterns and avoid surprises.
  </Accordion>

  <Accordion title="Handle quota errors gracefully">
    Always check for 429 errors and provide appropriate user feedback.
  </Accordion>
</AccordionGroup>

## Quota Reset Schedule

Quotas reset monthly on your signup anniversary:

* **Signed up on January 15** → Resets on the 15th of each month
* **Signed up on March 31** → Resets on the last day of each month
* Time zone: UTC

<Warning>
  Unused credits do NOT carry over to the next month. Use them or lose them!
</Warning>