Credits
=======

Every MCP tool call costs credits. Credits are tracked per API key with
rolling quotas.


How Credits Work
----------------

Each tool has a fixed credit cost that is deducted from your quota when the
tool is called. Bulk tools charge per item rather than per call -- for example,
parsing 10 User-Agent strings in a single bulk call costs 10 credits (1 per
UA), not 2 as a single parse would.

Quotas are tracked via Redis with a rolling time window. When your quota
resets, your full credit allowance is restored automatically. There is nothing
to top up or configure -- the system manages it based on your plan tier.


Credit Costs
------------

.. list-table::
   :widths: 45 15
   :header-rows: 1

   * - Tool
     - Credits
   * - ``apicrate-parse-user-agent``
     - 2
   * - ``apicrate-parse-user-agents-bulk``
     - 1 / UA
   * - ``apicrate-geolocate-ip``
     - 5
   * - ``apicrate-lookup-country``
     - 1
   * - ``apicrate-search-countries``
     - 3
   * - ``apicrate-validate-country-codes``
     - 1 / code
   * - ``apicrate-lookup-postal-code``
     - 2
   * - ``apicrate-validate-postal-code``
     - 1
   * - ``apicrate-search-postal-codes``
     - 3
   * - ``apicrate-list-postal-systems``
     - 2
   * - ``apicrate-get-postal-system``
     - 2
   * - ``apicrate-validate-postal-codes-bulk``
     - 2 / code
   * - ``apicrate-find-nearby-postal-codes``
     - 5
   * - ``apicrate-get-timezone-info``
     - 1
   * - ``apicrate-convert-time``
     - 1
   * - ``apicrate-compute-hash``
     - 1
   * - ``apicrate-hash-password``
     - 2
   * - ``apicrate-get-bible-verse``
     - 1
   * - ``apicrate-search-bible``
     - 3
   * - ``apicrate-check-email-risk``
     - 4
   * - ``apicrate-check-email-risk-bulk``
     - 4 / email


Quota Headers
-------------

Every response includes three headers that report your current quota status:

.. list-table::
   :widths: 30 70
   :header-rows: 1

   * - Header
     - Description
   * - ``X-Quota-Limit``
     - Total credits available in your current rolling window.
   * - ``X-Quota-Remaining``
     - Credits remaining before the next reset.
   * - ``X-Quota-Reset``
     - Unix timestamp when your quota window resets and credits are restored.

These headers are set on every successful response and on quota-exceeded
errors, so your client always has visibility into usage.


Exceeding Your Quota
--------------------

When your remaining credits reach zero, subsequent tool calls return an error
with the quota limit and the reset timestamp:

.. code-block:: text

   Quota exceeded. Limit: 1000, resets at: 1711497600

Wait for the reset window or upgrade your plan tier for a higher allowance.

.. note::

   The quota system is designed to **fail open**. If the Redis backend is
   temporarily unavailable, requests are allowed through rather than blocked.
   This ensures brief infrastructure issues do not disrupt your workflow.