Using the API

Rate limits

Per-key limits in one-minute windows across three buckets, reported in RateLimit-Policy and RateLimit headers, with Retry-After on a 429.

Limits apply per API key, in fixed one-minute windows. Every request a valid key makes counts against the overall bucket — a refused one (403) too; some also count against a second one.

Bucket	Default limit	Counts
`overall`	60 requests / minute	Every request
`search`	20 requests / minute	`POST /organizations/match`, `POST /organizations/contacts/match`, `POST /organizations/switchboards/match`, `POST /people/match`
`spend`	5 requests / minute	`POST /contacts/reveal` (dry runs included), and `POST /organizations/match`, `POST /people/match` or `POST /organizations/switchboards/match` when it reveals

GET /credits counts only against overall. An organizations/match, people/match or organizations/switchboards/match that reveals (reveal set, dryRun false) counts against overall, search and spend, also when it is refused (400 without an Idempotency-Key), just as a refused contacts/reveal counts against spend.

A request counts once however many items it carries, so batching 25 items per request is the way to more throughput. These are starting values; if your integration needs more, tell us at support@funnelfeedr.com.

Headers

Every response to a valid key, errors included, reports the buckets that request counted against, following the IETF RateLimit header fields draft:

RateLimit-Policy: "overall";q=60;w=60, "search";q=20;w=60
RateLimit: "overall";r=41;t=17, "search";r=3;t=17

RateLimit-Policy: per bucket, the quota q per window of w seconds.
RateLimit: per bucket, the requests r remaining in this window and the seconds t until it resets.

Slow down when r gets low rather than waiting for a 429.

When you hit a limit

HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json
Retry-After: 12
RateLimit-Policy: "overall";q=60;w=60, "spend";q=5;w=60
RateLimit: "overall";r=52;t=12, "spend";r=0;t=12

{
  "type": "https://funnelfeedr.com/developers/errors/rate_limited",
  "title": "Rate limit exceeded",
  "status": 429,
  "detail": "Rate limit exceeded for 'spend' (5/min). Retry after 12 seconds.",
  "code": "rate_limited",
  "retryable": true,
  "retryAfterSeconds": 12,
  "traceId": "00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01"
}

Wait Retry-After seconds, then retry. A rate-limited request did nothing: nothing was revealed or charged, so retrying it — with the same Idempotency-Key for a spend call — is safe.

Windows are aligned to the clock minute, so a burst at the end of one minute and the start of the next can briefly see up to twice the limit. Don't build on that.

Headers

When you hit a limit

Cookie Settings

Cookie Settings