---
updatedAt: 2025-12-25T12:42:17.000Z
agentTools:
  projectIndex: https://loyaltyapi.yotpo.com/llms.txt
---

# Guidelines & Conventions

Best practices, rate limits, and usage patterns for the Yotpo Loyalty & Referrals API.

# 🧭 Guidelines & Conventions

Before building with the Yotpo Loyalty & Referrals API, we recommend reviewing the following best practices, usage patterns, and limitations.

***

## 📈 Rate Limiting

To ensure fair usage and system stability, all API requests are rate-limited.

* You can make **up to 10 requests per second** per merchant account.
* If you exceed this limit, you'll receive a `429 Too Many Requests` error.
* All API responses include rate limiting headers that provide real-time information about your current usage and limits.

### 📊 Rate Limiting Headers

Every API response includes the following headers to help you monitor and manage your rate limit usage:

| Header                         | Description                                                       |
| ------------------------------ | ----------------------------------------------------------------- |
| `ratelimit-limit`              | The maximum number of requests allowed in the current time window |
| `ratelimit-remaining`          | The number of requests remaining in the current time window       |
| `ratelimit-reset`              | The number of seconds until the rate limit window resets          |
| `x-ratelimit-limit-minute`     | The maximum number of requests allowed per minute                 |
| `x-ratelimit-remaining-minute` | The number of requests remaining in the current minute            |

> **Note:** The actual values in these headers vary between API calls and depend on your current usage patterns.

### ⛑️ How to Avoid Rate Limiting

To prevent your application from hitting the rate limit:

* ✅ **Monitor rate limit headers** — Check `ratelimit-remaining` and `x-ratelimit-remaining-minute` on every response to track your usage
* ✅ **Implement adaptive throttling** — Use `ratelimit-reset` to calculate when to resume requests after approaching limits
* ✅ **Optimize requests** — Only fetch the data your app truly needs
* ✅ **Use caching** — Cache frequently accessed data to reduce API calls
* ✅ **Regulate request frequency** — Distribute requests across users and features to avoid bursts
* ✅ **Handle 429 errors gracefully** — Implement error handling for `429` responses and use **retry-after** logic
* ✅ **Back off intelligently** — When `ratelimit-remaining` is low, wait until `ratelimit-reset` seconds have passed before making more requests
* ✅ **Include metadata in requests** — Help monitor usage patterns (if available)

#### 💡 Best Practice: Using Rate Limit Headers

Here's how to effectively use rate limiting headers in your application:

1. **Check headers after each request** — Read `ratelimit-remaining` to know how many requests you have left
2. **Implement proactive throttling** — When `ratelimit-remaining` drops below a threshold (e.g., 10), slow down your request rate
3. **Respect reset times** — Use `ratelimit-reset` to schedule requests after the window resets instead of immediately retrying
4. **Monitor per-minute limits** — Track `x-ratelimit-remaining-minute` to avoid short-term bursts that could trigger rate limits
5. **Log header values** — Include rate limit header values in your application logs to help debug and optimize usage patterns

Example implementation pattern:

```javascript
// Pseudo-code example
const remaining = parseInt(response.headers['ratelimit-remaining']);
const resetIn = parseInt(response.headers['ratelimit-reset']);

if (remaining < 10) {
  // Slow down: wait until reset or add delay
  await delay(resetIn * 1000);
}
```

***

## �� API Explorer Usage

Each API reference page includes:

* 📘 **Live code examples** on the right side
* 🔄 A **language switcher** for Curl, Ruby, Java — and for Events, JavaScript
* ✅ Ready-to-copy requests and responses for fast testing

> These tools are great for learning the API, debugging quickly, or testing requests before integrating into your app.

***

## 🧩 Coming Soon

Additional conventions — like error codes, pagination, and response structure — may be documented here in the future.

***

## ✅ Next Steps

* Set up [Authentication](./about-authentication)
* Explore available [API endpoints](./table-of-contents)

# Sibling pages

* [Welcome](https://loyaltyapi.yotpo.com/reference/welcome.md)
* [Authentication](https://loyaltyapi.yotpo.com/reference/authentication.md)

# What’s Next

Learn how to authenticate API requests