Rate Limits

The Textingline API enforces per-key rate limits to ensure fair usage and platform stability.

Limits by endpoint

Endpoint	Limit	Window
`POST /api/v1/messaging/message`	60 requests	60 seconds
`POST /api/v1/messaging/broadcast`	1 request	60 seconds
`POST /api/v1/messaging/batch`	5 requests	60 seconds
Contact-management reads — contact GET, groups GET / LIST, custom-fields schema GET	150 requests	60 seconds
Contact-management writes — contact POST / PATCH, group-membership POST / DELETE	150 requests	60 seconds

Shared rate-limit buckets

The contact-management endpoints share two pooled buckets rather than per-endpoint limits:

contactApiRead (150 requests / 60 seconds) — pooled across every read endpoint in the Contact Management section: GET on /contacts/by-phone/{phoneNumber}, GET on /groups, GET on /groups/{id}, and GET on /contacts/custom-fields/schema.
contactApiWrite (150 requests / 60 seconds) — pooled across every write endpoint in the same section: POST / PATCH on /contacts/by-phone/{phoneNumber}, POST / DELETE on /contacts/by-phone/{phoneNumber}/groups/{groupId}.

If you saturate one bucket with one endpoint, subsequent calls to a different endpoint in the same bucket also hit the 429 — design your CRM-sync or batch-import code accordingly. The headers and Retry-After response are the same as for the messaging endpoints (described below).

Rate limit headers

Every API response includes headers that tell you your current rate limit status:

Header	Description	Example
`X-RateLimit-Limit`	Maximum requests allowed in the current window	`60`
`X-RateLimit-Remaining`	Requests remaining in the current window	`58`
`X-RateLimit-Reset`	Unix timestamp (seconds) when the window resets	`1741700000`

Exceeding the limit

When you exceed the rate limit, the API returns a 429 Too Many Requests response with an additional Retry-After header:

{
  "code": 33002,
  "message": "Rate limit exceeded",
  "status": 429,
  "moreInfo": "https://docs.smsfactory.com/docs/error-codes"
}

Header	Description
`Retry-After`	Number of seconds to wait before making another request

Daily messaging quota

In addition to per-second rate limits, each account has a daily messaging quota that limits the total number of messages you can send per day. When exceeded, the API returns error code 33012:

{
  "code": 33012,
  "message": "Daily messaging quota reached",
  "status": 429,
  "moreInfo": "https://docs.smsfactory.com/docs/error-codes"
}

Best practices

Monitor the headers. Check X-RateLimit-Remaining before sending batches to avoid hitting the limit.
Implement backoff. When you receive a 429, wait for the Retry-After duration before retrying.
Use broadcasts or batches for bulk sends. Instead of sending 10,000 individual messages, use a single broadcast (same message to all) or batch (unique message per recipient) request to stay well within rate limits.
Spread requests over time. If sending many individual messages, space them evenly across the rate limit window.