API rate limits and quota headers

To protect the platform from abuse and keep good performance for everyone, every organization has a per-minute rate limit on the API, based on its subscription plan. The limit applies per (user + organization) or per token, depending on how you authenticate.

Limits by plan

If your organization is on an unrecognized or trial plan, a safety cap of 300 req/min applies.

Quota headers

Every successful response includes:

• X-RateLimit-Limit: your plan's cap (requests per minute).
• X-RateLimit-Remaining: how many requests you have left in the current minute.

When you exceed the limit, the API returns 429 Too Many Requests with:

• Retry-After: seconds to wait before retrying.
• X-RateLimit-Reset: Unix timestamp when your quota resets.

Example: reading your remaining quota

curl -i -X GET "https://app.omnifox.io/api/v1/contacts" \
  -H "Authorization: Bearer YOUR_TOKEN" | grep -i ratelimit

X-RateLimit-Limit: 600
X-RateLimit-Remaining: 587

Tips

• If your integration polls frequently (e.g. checking for new messages), prefer processing outbound Webhooks instead of polling the API at short intervals — it uses far less quota.
• Design your client to honor Retry-After with exponential backoff instead of retrying immediately.

Troubleshooting

• Constant 429s even though your volume is low: multiple processes or scripts may be sharing the same user/token; they all draw from the same bucket.
• Need more quota: upgrade your plan from Settings > Plan and billing; the new limit takes effect automatically on the next minute boundary.