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.

Throughput and result limits

Constraint	Value
Concurrent sessions per network	500 — shared across all users and API keys on the network
Session idle timeout	10 minutes — idle sessions are closed server-side; Streamable HTTP clients renegotiate automatically on the next request
`search_activity` (`type="click"`) — max records returned	1,000 (not paginated)
`search_activity` (`type="conversion"`) — max records per page	100 (default 50) — paginated via `page_size` + `cursor`, no overall cap
`search_activity` (`type="click"`) — max date window	14 days
`search_activity` (`type="conversion"`) — minimum window	One full day in the network timezone (`YYYY-MM-DD 00:00:00` → `YYYY-MM-DD 23:59:59`) — shorter windows may return an error
`run_performance_report` — max rows per page	100
`run_performance_report` — max total rows (all pages combined)	500 — `result_capped: true` (with `row_limit`) is set when this ceiling drops rows
`list_offers`, `list_affiliates`, `list_entities` — max rows per page	100 (default 25) — a larger `page_size` is rejected with `INVALID_ARGUMENT`, not clamped
`list_entities` (`type="coupon_code"`) — max values per filter	100 per filter key (pipe-separated) — exceeding it returns `INVALID_ARGUMENT` naming the cap and the count received. Note the whole `filters` object is also capped at 4,096 chars, so long code values reach that limit before 100 of them fit — batch by `affiliate_id` or `offer_id` when codes are long
`list_traffic_health` (`uptime_incidents`, `domain_reputations`) — max rows per page	100 (default 100) — a larger `page_size` is rejected, not clamped
Rate limit	10 req/s per network — dedicated MCP bucket, shared across all users and API keys on the network. Independent from the REST API quota.

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 window is one second, not one minute — retry after roughly a second rather than backing off for a full minute. See Rate Limiting for the header semantics.

Parameter length limits

All string parameters are validated server-side before any backend call. A request that exceeds a limit is rejected immediately with an INVALID_ARGUMENT error — no partial processing occurs.

Sub-parameters (sub1–sub10, adv1–adv10, source_id)

sub1–sub10, adv1–adv10, and source_id are affiliate-controlled tracking values written directly to database columns. Their limits match the underlying column constraint.

Parameter	Max
`sub1`, `sub2`, `sub3`, `sub4`, `sub5`, `sub6`, `sub7`, `sub8`, `sub9`, `sub10`	600 chars
`adv1`, `adv2`, `adv3`, `adv4`, `adv5`, `adv6`, `adv7`, `adv8`, `adv9`, `adv10`	600 chars
`source_id`	600 chars

Common parameters (cursor, timezone, currency)

These limits apply across every tool where the parameter appears.

Parameter	Max
`cursor` (pagination token)	1,024 chars
`timezone` (IANA name, e.g. `America/New_York`)	64 chars
`currency` (ISO code, e.g. `USD`)	8 chars

Reporting tools

Parameter	Tool	Max
`dimensions`	`run_performance_report`	256 chars
`filters` (comma-separated `type:value` string)	`run_performance_report`	4,096 chars total
`metric_filters` (comma-separated conditions)	`run_performance_report`	512 chars
`sort_by`	`run_performance_report`	128 chars
`sort_direction`	`run_performance_report`	8 chars
`include`	`run_network_summary`	256 chars
Individual non-sub filter values (e.g. `country`, `status`, `offer_id`)	`search_activity`	64 chars each

Offer and affiliate tools

Parameter	Tool	Max
`include`	`get_offer`, `get_affiliate`	256 chars
`affiliate_ids`, `offer_ids`	`get_offer`, `get_affiliate`	1,024 chars
`can_run`	`get_affiliate`	8 chars
Individual filter values (`search`, `status`, `label`, etc.)	`list_offers`, `list_affiliates`	256 chars each

Generic entity tools

Parameter	Tool	Max
`type`	`get_entity`, `get_entity_schema`, `list_entities`	64 chars
`id`	`get_entity`	64 chars
`include`	`get_entity`	1,024 chars
`filters` (JSON object)	`list_entities`	4,096 chars
Individual `coupon_code` filter values (`type="coupon_code"`)	`list_entities`	64 chars each
`parameters` (JSON object)	`get_entity`	4,096 chars

Documentation search

Parameter	Max
`query`	512 chars
`source`	64 chars

Errors

When a tool call fails, the MCP Server returns a result with isError: true. The text field of that result is a JSON object with two fields:

{
  "code": "INVALID_ARGUMENT",
  "message": "Missing required parameter: 'transaction_id'."
}

The message is human-readable and safe to surface directly to an end user or AI agent. The code is a stable string your code can branch on without parsing prose. When a parameter limit is exceeded, the message always names the offending parameter, the allowed maximum, and the actual length received — and the server returns before any backend call is made:

{
  "code": "INVALID_ARGUMENT",
  "message": "Parameter 'sub1' exceeds the maximum length of 600 characters (got 847)."
}

Error codes

Code	Meaning	Common triggers
`INVALID_ARGUMENT`	A parameter is missing, malformed, or out of range	Missing required field (`transaction_id`, `from`/`to`, `dimensions`); invalid date format; a string parameter exceeds its length limit above
`UNAUTHENTICATED`	The API key was not recognized by Everflow	Key is missing, expired, or belongs to an affiliate/advertiser rather than a network user
`PERMISSION_DENIED`	The key is valid but lacks the required module permission for this tool	A key without Offer → Manage calling `get_offer`; a key without Reporting calling `run_performance_report`. See All Tools for the per-tool requirement
`NOT_FOUND`	The referenced record does not exist or is outside the key’s scope	A `get_entity` call referencing an ID that does not exist, or a record the key is not allowed to access
`RESOURCE_EXHAUSTED`	A rate limit was hit	More than 10 req/s for the network; back off and retry after roughly a second
`INTERNAL`	An unexpected error occurred in the Everflow backend	Transient service failure; try again. If it persists, email support@everflow.io

Two fields that are not errors

Two top-level keys can appear on a successful response and are easy to mistake for a problem:

Field	Means
`_untrusted_content`	The response contains fields authored outside Everflow (offer names, sub-params, referers). Informational, and present on most responses
`_security_notice`	A field value matched a prompt-injection pattern and was replaced with `[content removed: potential prompt injection]`

Neither sets isError. See Response safety.

Handling errors in a script

Check isError before processing content. The code lets you handle each class of error differently without string-matching the message:

import json

def call_tool(agent_response):
    for block in agent_response.content:
        if not hasattr(block, "text"):
            continue

        # Attempt to detect an error envelope: {"code": "...", "message": "..."}
        try:
            payload = json.loads(block.text)
        except json.JSONDecodeError:
            # Not JSON — treat as a successful plain-text result
            return block.text

        # Valid JSON but not an error envelope — successful structured result
        if "code" not in payload:
            return block.text

        code = payload.get("code")
        message = payload.get("message", "Unknown error")

        if code == "INVALID_ARGUMENT":
            raise ValueError(f"Bad request: {message}")
        elif code == "UNAUTHENTICATED":
            raise PermissionError(f"Auth failed: {message}")
        elif code == "PERMISSION_DENIED":
            raise PermissionError(f"Insufficient permissions: {message}")
        elif code == "NOT_FOUND":
            raise LookupError(f"Not found: {message}")
        elif code == "RESOURCE_EXHAUSTED":
            raise RuntimeError(f"Rate limited: {message}")
        elif code == "INTERNAL":
            raise RuntimeError(f"Server error: {message}")

AI agents read the message field automatically and will describe the problem in natural language without any extra handling on your part. Error code parsing is only necessary when you are processing MCP tool results programmatically in a script.

​Throughput and result limits

​Parameter length limits

​Errors

​Error codes

​Two fields that are not errors

​Handling errors in a script

Throughput and result limits

Parameter length limits

Errors

Error codes

Two fields that are not errors

Handling errors in a script