<!-- The markdown copy of https://oppalerts.com/docs/getting-started/how-the-api-handles-requests . All pages: https://oppalerts.com/docs/llms.txt -->

[Documentation](https://oppalerts.com/docs/) / [Getting Started](https://oppalerts.com/docs/getting-started/) / How the API Handles Requests

# How the API Handles Requests

Understand why a request is rejected, whether it counts toward your daily limit, and when to try again.

These rules apply to the API and to the MCP server. There is no queue. A call that cannot run immediately is rejected. Send it again.

Your team members' calls count toward your account usage and share the same limits.

## One search at a time

Each `news_` and `prospects_` tool is an index search. Only one index search runs at a time for an account.

- A search sent while another is running is rejected immediately with HTTP 429 and the error `one_at_a_time`. The error message is "An index search is running for this account. Only one search can run at a time. Try again in a few seconds."
- The rejected search does not count toward your daily search limit.
- What to do: wait a few seconds and send it again. Do not send index searches in parallel.

## One change at a time

A call that changes data, for example [`campaigns_update`](https://oppalerts.com/docs/mcp/campaigns_update), runs only when no other change is running for the account.

- A change sent while another change is running is rejected immediately with HTTP 429 and the error `one_at_a_time`. The error message is "Another change is running for this account. Only one change can run at a time. Send the call again in a few seconds."
- The rejected call does not count toward your daily limit and is not queued.
- What to do: send the call again after a few seconds.

## A search that takes too long

Each search statement stops after 10 seconds.

- A stopped search returns HTTP 422 and the error `search_stopped`. The error message explains how to make the search more specific.
- A stopped search counts as 1 search.
- A search with a vector and with words or conditions sends 2 statements: first a count, then the search. Each statement has its own 10-second limit.
- What to do: do not send the same search again. Narrow it with more specific words, a higher minimum PR, or a shorter date range.

## Daily counts

- An accepted call counts as 1 call toward the daily limit.
- A rejected call does not count toward the daily limit. A stopped search does count.
- All index searches in an account share one daily count. Each other tool has its own daily count.
- The counts reset at 04:00 New York time.
- [`account_calls_left`](https://oppalerts.com/docs/mcp/account_calls_left) shows the calls left today.

The limits for each plan are on [Usage and Daily Limits](https://oppalerts.com/docs/getting-started/usage-and-daily-limits).

## Large result counts

These rules apply to a search with a vector (semantic similarity), for example with [`news_search`](https://oppalerts.com/docs/mcp/news_search).

- `total_matches` is never more than 10,000. 10,000 means 10,000 or more.
- `partial` is true when more than 15,000 pages match. The results then come from only a subset of matching pages.
- What to do when `partial` is true: make the search more specific.

## Strict fields

- Unknown fields, empty text, and out-of-range values are rejected. The error names the field.
- Search tools do not apply values you did not send, except `results_limit`, which defaults to 100.

## The request log

- Each request with a valid token creates an entry in the account request log. The [Usage](https://oppalerts.com/docs/account/usage) page and [`account_usage`](https://oppalerts.com/docs/mcp/account_usage) show these entries.
- A rejected request also creates an entry, with its status, for example 403 or 404. The calls that an MCP client makes to connect (`initialize`, `tools/list`, and `ping`) create log entries but do not count toward daily usage.
- These requests do not create log entries: a request rejected with HTTP 429 because another search or change is running, a call of `account_calls_left` through the API or MCP, and a request with no valid token (HTTP 401).

## Server errors

If the server cannot save a change, it returns HTTP 500 and the error `db_error`. No data was changed.

## Related Pages

- [Usage and Daily Limits](https://oppalerts.com/docs/getting-started/usage-and-daily-limits) Know how many calls your account has left today, and see who used them.
- [Your First API Call](https://oppalerts.com/docs/getting-started/your-first-api-call) Make three calls to the OppAlerts API and read the full answer of each one.
- [account_calls_left](https://oppalerts.com/docs/mcp/account_calls_left) The calls left today, and when the counts reset.
