Limits & Errors - Everflow API

Everything that can stop a tool call short: the ceilings it runs into, and the errors it returns when it does. For what each tool takes and returns, see Tools.

Limits at a glance

Constraint	Value
`search_activity` (`type="click"`), window	14 days at most
`search_activity` (`type="click"`), reachable clicks	The newest 1,000 clicks of the window. `truncated` is `true` when the scan reaches 1,000 clicks (which includes a window with exactly 1,000), so narrow the window or add filters when completeness matters
`search_activity` (`type="conversion"`), window	Within the last 365 days and at most 367 days long. A window reaching further back is clamped to the last 365 days, and one entirely older is refused
`search_activity` (`type="conversion"`), explicit times	A window with explicit `HH:MM:SS` times on both ends must be at least 23 hours, so use whole `YYYY-MM-DD` days. Click search accepts shorter timed windows
`search_activity`, rows per page	1 to 100 (default 50)
`run_performance_report`, window	367 days at most
`run_performance_report`, rows	500 across all pages. `meta.result_capped` is `true` (with `meta.row_limit`) when the cap drops rows, and the totals still cover every matched row
`run_performance_report`, rows per page	1 to 100 (default 50)
`run_performance_report`, `dimensions`	10 at most, and only one time dimension (`hour`, `date`, `week` or `month`)
`list_payments`, window	An explicit `from` to `to` window is at most 366 days. Default: the last 90 days ending today. A request with an `invoice_id` and no dates covers all of that invoice’s payments
`list_payments`, rows per page	1 to 100 (default 25)
`list_offers`, rows per page	1 to 100 (default 25)
`list_offers`, `offer_ids`	25 ids at most
`list_offers`, sort ceiling	A `sort_by` other than `id` works on at most 2,000 matching offers and is refused when more match, so narrow the filters first. A sort near the ceiling can take several seconds
`list_invoices`, rows per page	1 to 100 (default 25)
`list_invoices`, sort ceiling	A `sort_by` other than `invoice_id` works on at most 500 matching invoices and is refused when more match, so narrow the filters first
`list_entities`, rows per page	1 to 100 (default 25)
`get_invoice`, lines per page	1 to 100 (default 100). A page of lines is also cut at about 12,000 characters
`get_invoice`, payments	The first 50 recorded against the invoice. `payments_total` gives the full count, and `list_payments` with the same `invoice_id` lists every one
`get_offer`, ids per batch	25 via `offer_ids`, but 10 when `include` has `payout`, `caps`, `targeting`, `description`, `tracking_url`, `urls`, `creatives` or `integrations`. Exceeding it returns `INVALID_ARGUMENT` naming the cap
Page character budget	`search_activity`, `list_invoices` and `list_payments` cut a page to fit about 20,000 characters (the first row is always returned), so a page can hold fewer rows than `page_size`. A note says so. Keep paging while `has_more` is `true`
Long values in rows	Cut at 300 characters in raw activity rows and in invoice and payment notes
Rate limit	10 requests per second per partner (a burst of up to 10, refilled at 10 tokens per second)
Reporting allowance	Reports on detail dimensions and click searches draw on an hourly allowance that is the same one the Affiliate API uses, shared by all the partners of your network, so another partner’s use can run it out for you too. When it is used up, the call returns `RESOURCE_EXHAUSTED` (see below)
Idle session	Cleaned up after 10 minutes. The client keeps working on the same session id

Paging

While has_more is true, pass next_cursor back as cursor with the same filters, window, sort and page_size. A cursor only works for the partner and the query that produced it, and is at most 1,024 characters.

Rate limit

A throttled request returns 429 Too Many Requests with Retry-After: 1, alongside the X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. The body is:

"Too many requests, MCP is limited to 10 requests per second per partner"

The window is one second, not one minute, so retry after roughly a second.

Reporting allowance

A run_performance_report on detail dimensions and a click search can return RESOURCE_EXHAUSTED with this exact message:

{
  "code": "RESOURCE_EXHAUSTED",
  "message": "Reports on detail dimensions and click search are temporarily rate limited. Reports on summary dimensions still work. The limit resets at the top of the hour (UTC)."
}

Run a report on summary dimensions in the meantime, or retry after the top of the hour (UTC).

Parameter length limits

String parameters are validated before any backend call. A value over its limit is refused with INVALID_ARGUMENT.

Parameter	Tool	Max
`sub1` to `sub10`, `adv1` to `adv10`, `source_id`, `event_name`, `coupon_code`	`search_activity`	600 characters each
Every other filter value	`search_activity`	64 characters each
`cursor`	all paged tools	1,024 characters
`dimensions`	`run_performance_report`	256 characters
`filters`	`run_performance_report`	4,096 characters
`filters`	`list_entities`	10 filters at most, 256 characters per value
`search`, `status`, `category`, `country`, `platform`, `channel` and the other text filters	`list_offers`	256 characters each
`offer_ids`	`list_offers`, `get_offer`	1,024 characters
`search`	`list_invoices`	100 characters
`type`	`get_entity_schema`, `list_entities`	64 characters
`query`	`search_documentation`	512 characters
`source`	`search_documentation`	64 characters

Filter values may not contain quotes, backslashes, control characters or emoji. Exclusion syntax such as !US is refused on report filters, on every activity filter and on the list_offers country filter. Report filters refuse empty values; an empty list_offers search or country, or an empty activity sub1 or country, is read as no filter.

Size limits

Content	Limit
Other offer text	Cut at 1,000 characters
Offer URLs	Cut at 2,048 characters
Offer `description`	Cut at 4,000 characters
Creative code	Cut at 2,000 characters, with at most 50 creatives listed (`creatives_total` gives the full count)
`payout` `variables` and `offer_urls`, `integrations` product feeds and deals	25 of each at most
Raw activity values and invoice and payment notes	Cut at 300 characters

A cut value in an offer carries a [truncated: N of M characters shown] marker.

Errors

When a tool call fails, the result has isError: true and its text is a JSON object:

{
  "code": "INVALID_ARGUMENT",
  "message": "Parameter 'page_size' must be a whole number from 1 to 100."
}

Field	Present	Meaning
`code`	Always	A stable string to branch on
`message`	Always	Human-readable text that is safe to show
`hint`	Optional	What to change before retrying
`suggestions`	Optional	Candidate values, for example the closest valid one

Error codes

Code	Meaning	What to do
`INVALID_ARGUMENT`	A parameter is missing, malformed, unknown or out of range: a dimension, filter, window, sort or argument the tool does not accept, or a value over its limit	Read the message, which names the problem, and correct the call
`UNAUTHENTICATED`	The key was not recognised	Rarely returned, because a bad key is answered with HTTP `401` before any tool runs
`PERMISSION_DENIED`	The call is not permitted for your account, for example MCP no longer enabled during a session	See the gate rows below
`NOT_FOUND`	The record does not exist or is not available to you, with the same wording for both	Check the id
`RESOURCE_EXHAUSTED`	The reporting allowance is used up	Use a summary-dimension report, or retry after the top of the hour (UTC)
`INTERNAL`	A server-side failure. The message is a fixed sentence for that tool, for example “Failed to retrieve account info.”	Try again, and if it persists email support@everflow.io

HTTP-level answers

Authentication, access and the rate limit are answered by the HTTP layer before any tool runs, in this order, with a plain JSON message instead of the envelope above.

Status	Message	Cause
`401`	`Unable to authenticate request`	No API key header
`401`	`No authentication method found`	Unknown or inactive key
`403`	`This endpoint requires an Affiliate API key`	A Network API key sent to `/affiliate`
`403`	`Out of realm`	An Affiliate API key sent to the root URL (the Network MCP)
`403`	`MCP is not enabled for your account. Ask your network to enable it.`	MCP is not enabled for your account. Returned on every request, session start included. Enabling or disabling a partner can take up to a minute to apply
`503`	`Access could not be verified. Please try again.`	The access check could not be completed. Retry
`429`	`Too many requests, MCP is limited to 10 requests per second per partner`	Rate limit (see above)

A request refused with 403 does not use any of your rate limit.

Sessions

Situation	Result
MCP disabled for your account during a session	`PERMISSION_DENIED` with the “MCP is not enabled for your account” message, for up to a minute before the connection itself is refused with `403`
Idle session	Cleaned up on the server after 10 minutes. A client keeps working on the same session id, so it needs no reconnect logic

​Limits at a glance

​Paging

​Rate limit

​Reporting allowance

​Parameter length limits

​Size limits

​Errors

​Error codes

​HTTP-level answers

​Sessions