FloPay MCP limits on concurrency, request and result size, and time, how rate limits show up in results, and how to recover from every error it returns.

Limits and errors

FloPay MCP returns problems in two ways. A request it cannot process gets a JSON-RPC error. A tool call that runs but fails comes back as a normal result with isError set to true, with details in structuredContent. This page lists both, with what to do next.

Limits

Limit	Value	What happens when you reach it
Read-only tool calls running at once	eight per operator, merchant, and client application	The call returns the `concurrency_limit` tool error.
Mutating tool calls running at once, previews included	one per operator, merchant, and client application	The call returns the `concurrency_limit` tool error.
Request size	256 KiB	JSON-RPC error `-32600`.
Result size	256 KiB	The `result_too_large` tool error, or JSON-RPC error `-32603` when the whole response is too large. FloPay MCP never truncates a result.
Time for a tool call	30 seconds	The `backend_unavailable` tool error with `Backend deadline exceeded.`
Tools per `tools/list` page	50	Follow `nextCursor` to the next page.
Tool search results	50	Use a more specific query.
Knowledge search results	20, each with a snippet of up to 1,024 characters	Read a result for its full text, or use a more specific query.

Concurrency limits apply on each FloPay MCP server, and the FloPay API applies its own limits across all of them.

Tool results must be JSON. Export tools produce a file stream rather than JSON, so through FloPay MCP they answer Backend returned a non-JSON response. or result_too_large. Run exports through the FloPay API or the dashboard instead.

Narrow a large result

A result_too_large error means the answer was bigger than FloPay MCP can return in one piece. Ask for less instead of retrying the same call:

Lower limit on list tools and page through results with page.
Add filters and a shorter time window, such as from and to on reporting tools.
Fetch a single record by its ID instead of listing records.

Each tool's arguments, limits, and filters are in the Tool reference.

Rate limits

FloPay MCP does not add its own rate limit beyond the concurrency limits above. When the FloPay API limits a call, the tool result has isError set to true, flopay/httpStatus set to 429, and flopay/rateLimit in _meta with the limit, remaining, reset, and retryAfter values the API sent. Wait at least retryAfter seconds before you retry, and add backoff when no retryAfter is given.

Every tool also declares a rate-limit tier, such as read, aggregate, restricted, or mutation, in the Tool reference. Tiers classify the policy each tool belongs to. Separate limits for each tier are not yet enforced, so rely on the 429 responses, not on the tier, when you plan retries.

Some operations have limits of their own. Export tools answer 429 when export capacity is exhausted, and client registration answers 429 with too_many_requests when one IP address registers too often.

Recover from errors

JSON-RPC errors

Code	Message	Cause	What to do
`-32001`	Authentication required.	No `Authorization` header, or a scheme other than `Bearer` or `Basic`. The response also carries a `WWW-Authenticate` challenge.	Send `Authorization: Bearer <access token>`.
`-32001`	Authentication failed.	The token expired, was issued for another server, or no longer grants access to the merchant.	Refresh the token, or sign the operator in again.
`-32020`	Header mismatch: required routing headers must match the JSON-RPC request.	`MCP-Protocol-Version`, `Mcp-Method`, or `Mcp-Name` does not match the message.	Set the headers from the message, as shown in Connect any MCP client.
`-32022`	Unsupported protocol version.	The protocol version is not `2026-07-28`. `error.data.supported` lists the versions FloPay MCP accepts.	Send `2026-07-28` in the header and in `_meta`.
`-32602`	Invalid MCP request metadata.	`io.modelcontextprotocol/clientCapabilities` is missing, or its `elicitation` value is not an object.	Send the capabilities object on every request.
`-32602`	Unknown or unavailable tool.	The tool does not exist, or this request cannot use it: the token lacks its scope, the operator's role does not allow it, or the client did not declare form elicitation for a mutating tool.	Check the tool's roles and scopes in the Tool reference, and see Confirmed actions.
`-32602`	Unknown or expired tool cursor.	The `tools/list` cursor is malformed, or the tools changed since it was issued.	List tools again from the first page.
`-32602`	Invalid action confirmation response.	A confirmation call is missing `requestState`, an `accept` has no idempotency key, or the `action` is not `accept`, `decline`, or `cancel`.	Send the confirmation as shown in Confirmed actions.
`-32002`	Resource not found or no longer fresh.	The resource URI does not exist, or its content expired.	Search again with `flopay/search` and read a current result.
`-32603`	Backend action preview is invalid.	FloPay rejected a mutating tool's preview, for example because the arguments are invalid or the operator can no longer run the action.	Check the arguments against the Tool reference, and check the operator's role.
`-32603`	Response exceeds 256 KiB; narrow the request.	The complete response was too large to send.	Narrow the request.
`-32601`	Method not found.	FloPay MCP does not support the method, such as prompts.	Use the tools and resources methods.
`-32600`	Invalid JSON-RPC request.	The body is not a single JSON-RPC message. Batches are not supported.	Send one message per request.
`-32600`	Request exceeds 256 KiB.	The request body is larger than the limit.	Send smaller arguments.

An unexpected failure answers 500 with JSON-RPC error -32603 and Internal server error. Retry once, and report it if it repeats.

Tool errors

These results have isError set to true and structuredContent.error holding a code and message:

Code	Message	What to do
`concurrency_limit`	Too many concurrent operations for this FloPay principal.	Wait for running calls to finish, then retry.
`backend_unavailable`	Backend invocation failed.	A read-only call can be retried with backoff. For a confirmed action, follow Retry an action.
`backend_unavailable`	Backend deadline exceeded.	The call took longer than 30 seconds. Narrow a read-only call. For a confirmed action, do not assume it failed: follow Retry an action.
`result_too_large`	Result exceeds 256 KiB; narrow the query or use pagination.	Narrow the request.

FloPay API errors

Any other result with isError set to true carries the FloPay API response body in structuredContent and its status in flopay/httpStatus. Each tool's possible statuses are in the Tool reference.

Status	What it means	What to do
`400`	The arguments failed validation.	Compare them with the tool's arguments in the Tool reference.
`401`	The credential stopped working during the call.	Refresh the token and call again.
`403`	The operator's role or the token's scopes do not allow the call. A body with `insufficient_scope` names the missing scope in `scope`.	Reconnect with the scope the error names, or ask a merchant owner to change the operator's role.
`404`	No record with that ID exists for this merchant.	Check the ID, and remember that FloPay MCP only sees the merchant chosen at sign-in.
`409`	A confirmation or idempotency conflict.	Follow Confirmed actions.
`424`	A payment provider behind FloPay could not be reached.	Retry later.
`429`	A rate limit or capacity limit.	See Rate limits.
`503`	A dependency is unavailable, or an action's outcome is unclear.	Retry read-only calls later. For an action, read the `reconciliation` field and follow Retry an action.

OAuth errors

Sign-in, token, and registration errors use the OAuth error and error_description fields. Connect any MCP client lists them with the fix for each.

Site navigation

Limits and errors

Limits and errors

Limits

Narrow a large result

Rate limits

Recover from errors

JSON-RPC errors

Tool errors

FloPay API errors

OAuth errors

On this page