Guides and reference

Rate limits

Limits are per API key and per endpoint. Over a limit ICON answers 429 with Retry-After.

#Defaults

Endpoint	Per minute	Burst
Search: `POST /api/v1/engine/search`	60	10
Results polling: `GET /api/v1/engine/results/{icon_lead_id}`	600	600
Submit: `POST /api/v1/engine/leads`	120	120
Duplicate pre-check: `POST /api/v1/engine/dupe-check`	30	10

Each key and endpoint has its own budget. It refills continuously (per minute ÷ 60 each second) and holds at most the burst, so a key can send a burst at once and then its steady rate. Treat the numbers as your ceiling, not a guarantee of capacity. ICON can set other limits on a key; ask your ICON contact.

#Over a limit

A call over a limit may be refused:

http

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

{
  "code": "RATE_LIMITED",
  "status": "failed",
  "reason": "Too many requests",
  "retryable": true,
  "retry_after_seconds": 2
}

Wait the Retry-After seconds, then retry. See Errors and retries.

#Staying under

Poll results no faster than poll_after_ms and stop at processing_done.
Search once per lead. Submit only results the consumer chose.
Use one key per integration so one busy integration cannot slow another.