Skip to main content

Rate Limiting

urelay enforces daily limits on new contacts per phone line to prevent spam and protect your phone numbers.

How it works​

Each phone line has a daily_contact_limit (default: 50). This limits the number of new contacts you can message per day per line.

What counts as a "new contact"​

A contact is considered new if:

  • You have never exchanged messages with them on this phone line
  • They have not sent you a message first (inbound-first contacts are free)

What does NOT count​

  • Contacts who messaged you first (they initiated the conversation)
  • Contacts with any prior message history on the line
  • Follow-up messages to existing contacts (unlimited)

Rate limit error​

If you exceed the daily limit, the API returns:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Daily new contact limit reached for this phone line",
    "details": {
      "phone_line_id": "cmlsxywe60000qq01704dovyf",
      "daily_limit": 50,
      "used": 50,
      "resets_at": "2026-02-20T00:00:00.000Z"
    }
  }
}

The HTTP status code is 429 Too Many Requests.

Reset schedule​

Limits reset at midnight UTC each day. The resets_at field in the error response tells you exactly when.

Best practices​

  • Check the rate limit before bulk operations
  • Spread outbound messages throughout the day
  • Use multiple phone lines for higher throughput
  • Prioritize responding to inbound messages (they don't count against the limit)