> ## Documentation Index
> Fetch the complete documentation index at: https://developers.everflow.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Limits & Errors

> Windows, page sizes, rate limits, length limits and the error codes every tool on the Affiliate MCP server can return.

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](/ai-automation/affiliate-mcp/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:

```json theme={null}
"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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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](mailto: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 |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.