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

# Rate Limits

> API rate limits and best practices

Paymnt Cloud enforces request limits based on your **pricing plan**.\
Your **current limit** (e.g., requests per second) is shown in **Dashboard → Settings → Rate limits**. When you need more throughput, upgrade your plan or contact Support.

> Source of truth: the Dashboard. Numbers in examples below are illustrative only.

***

## What is limited

* **API request count.** Each HTTP request to the Paymnt Cloud API counts toward your plan’s limit.
* **Environment awareness.** Limits may differ for **Sandbox** and **Production** (check the Dashboard).
* **How to view your limit.** Open **Dashboard → Settings → Rate limits** to see your effective limit for the current environment.

***

## Responses & headers

When you're near or over the limit, responses may include standard headers (when available):

```text theme={null}
X-RateLimit-Limit:       plan limit for the current window
X-RateLimit-Remaining:   remaining requests in the window
X-RateLimit-Reset:       when the window resets (epoch or seconds)
Retry-After:             seconds to wait when 429 is returned
```

If you exceed your plan, the API returns **HTTP 429 Too Many Requests**:

```json theme={null}
{
  "error": {
    "type": "rate_limit",
    "code": "CE_RL_429",
    "message": "Too many requests",
    "request_id": "req_XXXX",
    "status": 429
  }
}
```

Always respect Retry-After if present.

***

## Client guidance

* **Throttle on your side.** Keep your average request rate ≤ your plan limit
* **Back off on 429.** Pause for Retry-After seconds (or a short delay) and retry
* **Use idempotency on writes.** Prevent duplicates when retrying POST/PUT/PATCH. See [Idempotency](/pages/essentials/idempotency)
* **Reduce chatter.** Cache frequent reads, paginate, and avoid tight polling loops. Prefer events where possible. See [Webhooks — Overview](/pages/webhooks/overview)
* **Monitor.** Log request\_id and, when present, rate headers; alert before you hit the limit

***

## Minimal retry example (Node)

```javascript theme={null}
function sleep(ms){ return new Promise(r => setTimeout(r, ms)); }

export async function apiCall(path, { method="GET", headers={}, body } = {}) {
  const base = process.env.PAYMNT_BASE_URL || "https://sandbox.paymnt.cloud";
  for (let attempt = 1; attempt <= 4; attempt++) {
    const res = await fetch(`${base}${path}`, {
      method,
      headers: {
        "Accept": "application/json",
        "api-key": process.env.PAYMNT_API_KEY,
        ...(method !== "GET" && { "Content-Type": "application/json" }),
        ...headers
      },
      body: body ? JSON.stringify(body) : undefined
    });

    const text = await res.text();
    const data = text ? JSON.parse(text) : null;

    if (res.ok) return data;

    if (res.status === 429 && attempt < 4) {
      const retry = parseFloat(res.headers.get("Retry-After") || "1");
      await sleep(retry * 1000);
      continue;
    }

    const err = data?.error || { status: res.status, message: "Request failed" };
    throw new Error(`${err.type || "error"} ${err.code || res.status} (${err.request_id || "no-request-id"})`);
  }
}
```

***

## Need higher limits?

* **Upgrade your plan** in the Dashboard, or
* **Contact Support** with your expected requests per second, burst patterns, and endpoints you plan to scale

***

## Related

* [Authentication](/pages/essentials/authentication)
* [Idempotency](/pages/essentials/idempotency)
* [Webhooks — Overview](/pages/webhooks/overview)
* [Error Codes](/pages/essentials/error-codes)