Skip to content
RouteDeskDevelopers

Lead intake API

Rate limits and retries

The limit is generous for one lead per request. What needs care is retrying without creating the same lead twice.

The rate limit

You can send 120 requests per minute from one IP address. Every request counts, including ones that are rejected.

Every response carries headers that show where you stand:

  • X-RateLimit-Limit: requests allowed per window.
  • X-RateLimit-Remaining: requests left in the current window.
  • X-RateLimit-Reset: seconds until the window resets.

Over the limit, you get 429 with a Retry-After header in seconds. The body's retry_after field carries the same number.

Headers · 429
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json; charset=utf-8
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 29
Retry-After: 29
Body · 429
{
  "type": "https://routedesk.com/errors/rate-limited",
  "title": "Rate Limit Exceeded",
  "status": 429,
  "detail": "Rate limit exceeded. Retry after 29 seconds.",
  "retry_after": 29,
  "instance": "/api/v1/public/leads",
  "request_id": "01a1d690-946b-75fb-8fa2-6b6106b06cb5"
}

When to retry

  • 201Never resend

    The lead exists. Sending it again creates a second lead.

  • 422Fix, then send

    The same goes for 400, 401, 403 and 413. Resending the same request gets the same answer, so fix the request or the key first.

  • 429Wait, then resend

    Wait the number of seconds in Retry-After. No lead was created.

  • 500Resend with backoff

    No lead was created. Wait a few seconds and try again, doubling the wait each time, and give up after a few attempts.

Timeouts and duplicate leads

If a request times out or the connection drops, you cannot tell whether the lead was created. Sending it again may create a second copy. There is no idempotency key yet that would let RouteDesk recognize a repeat.

To keep duplicates rare:

  • Allow at least 10 seconds before treating a request as timed out.
  • Retry a timed-out request once, not in a loop.
  • Never resend a lead that already got a response, whatever the status.

A second copy is not lost work for the broker. When a lead arrives with the same phone number or email as one from the last 30 days, RouteDesk still creates it and marks it as a possible duplicate for the broker to review.