Limits

Flume counts some calls per partner per UTC day. Over a limit, the call returns 429 RATE_LIMITED with a Retry-After header. Counters reset at 00:00 UTC.

What are the daily limits?

Call	Limit per partner per UTC day
POST /search	1,000
POST /request-instant-quote	200
POST /users/trigger-verification	500
POST /detect-category	2,000
POST /deep-links	2,000

• A limit is per partner, not per user. All your users share it.
• Reads spend nothing: GET /searches/{search_session_uuid}, GET /quotes/{quote_uuid}, GET /products/{sku_uuid}, GET /filters.
• A search that fails because search is unavailable (503) is not counted.
• These are defaults. Flume can set a different limit for an environment.
• Flume can also set a limit per user. See Is there a limit per user?.

What does a 429 look like?

HTTP/1.1 429 Too Many Requests
Retry-After: 28412
Content-Type: application/json

{
  "error": {
    "code": "RATE_LIMITED",
    "message": "Today's limit of 1,000 searches is used up. It resets at 00:00 UTC.",
    "field": null,
    "request_id": "e19b8889-a63b-4000-9dbe-ffd5b9157bd5"
  }
}

• Retry-After is the number of seconds until 00:00 UTC.
• Flume also protects its total capacity. The message then reads "Flume can't take more searches today." The status and code are the same.

How do you track usage?

• There are no X-RateLimit-* headers. Only Retry-After on the 429.
• No endpoint reports usage or what is left.
• Count your own calls if you need to warn users before the limit.
• On live, a network-level limit per IP address can also return a 429 with no JSON body and no Retry-After. Back off and retry.

Is there a limit per user?

Not by default. Flume can set a daily limit per user on your partner account, for searches, for instant quotes, or for both. Ask Flume whether your account has one.

Counted	What counts as one
Search	The first page of a POST /search, and each new search the user runs in the iframe. A later page of the same search does not count
Instant quote	Each POST /request-instant-quote that Flume accepts

• The count is per user's Flume account, per UTC day. It resets at 00:00 UTC.
• Calls from your backend and the user's work in the iframe share one count.
• Over the limit, the call returns 429 DAILY_LIMIT_REACHED with a Retry-After header.
• A call refused by the user's limit does not count against your limit per partner.
• A search that fails because search is unavailable (503) is not counted.
• In the iframe, the iframe tells the user. Your page receives no message.

{
  "error": {
    "code": "DAILY_LIMIT_REACHED",
    "message": "Today's limit of 20 searches is used up. It resets at 00:00 UTC.",
    "field": null,
    "request_id": "e19b8889-a63b-4000-9dbe-ffd5b9157bd5",
    "details": {
      "kind": "SEARCH",
      "limit": 20,
      "reset_at": "2026-11-12T00:00:00Z",
      "retry_after_s": 30120
    }
  }
}

The numbers in this sample are examples. Read the real limit from details.limit.

Field in details	Meaning
kind	SEARCH or QUOTE
limit	The user's limit per UTC day
reset_at	When the count resets, in UTC
retry_after_s	Seconds until then. The same value as Retry-After

Other users are not affected. Tell this user when they can try again.

Which other limits are there?

Limit	Value	Code
Wait before a code resend	30 seconds	VERIFICATION_RATE_LIMITED
Codes per mailbox	5 in 24 hours	VERIFICATION_RATE_LIMITED
Codes per user IP address, when you send X-Flume-Client-IP	30 in 1 hour	VERIFICATION_RATE_LIMITED
Open sales requests per user	60	422 VALIDATION_FAILED
Keys issued, sandbox	10 in 24 hours	KEY_ROTATION_RATE_LIMITED
Keys issued, live	1 in 24 hours	KEY_ROTATION_RATE_LIMITED

What are the size limits?

Thing	Limit
Search photo	6,000,000 bytes. JPEG, PNG or WebP
Results per search	50
Results per page	24
Item photo Flume fetches for the iframe	25 MB, https, no redirects, 10 second timeout
item.image_urls, item.document_urls	20 entries each
item.labels, item.rooms	100 entries each
Idempotency-Key	255 characters
Active keys, sandbox	5
Active keys, live	2

How long do things last?

How long each thing lasts. Every timer, code and link in the integration, shortest first. The scale is logarithmic.

Read this diagram as text

1. Ready timer: 15 seconds. On your page. When it fires, remove the iframe and offer a retry.
2. Reply to a save: 60 seconds. After that the iframe treats the save as failed.
3. Launch code: 120 seconds, one use. Inside iframe_url. Set the iframe src at once.
4. Connect code: 120 seconds, one use. Exchange it at once.
5. Verification code: 10 minutes. The emailed code the user types in the iframe.
6. Iframe session: 12 hours. From its first open. Then flume:close_iframe with reason expired.
7. Image links: about 24 hours. In the save payload. Copy the bytes when you save.
8. Open in Flume link: 7 days, one use. Create it on the click. Never store it.
9. Instant quote prices: 30 days. Until pricing.valid_until in the save payload.
10. Unused session: 30 days. A session nobody reopens is dropped. The next open starts fresh.
11. User access token: no expiry. Replaced when the user verifies again, or revoked by you.

Thing	Lifetime
Verification code	10 minutes, 3 tries
Launch code, in iframe_url	120 seconds, one use
Connect code	120 seconds, one use
Iframe session	12 hours from its first open. A reopen does not restart them
Idle iframe session state	30 days
Instant quote prices	Until valid_until: 30 days today. Always read the field
Deep link	7 days, one use
Image links	About 24 hours. In the sandbox they can stop working earlier
Idempotency key	24 hours
Replaced key during rotation	overlap_days: default 7, 0 to 30
User access token	No expiry
Search (search_session_uuid)	No expiry

How should you handle a limit?

1. Read Retry-After.
2. Stop sending that call until then. Other calls still work.
3. Tell the user plainly. error.message is written for them.
4. Ask Flume if you need a higher limit.