> For the complete documentation index, see [llms.txt](https://mcp-docs.nichefire.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://mcp-docs.nichefire.com/errors-and-limits/errors.md).

# Errors

Reference document for errors retrieved by the MCP

When a request cannot be completed, Nichefire returns an error response describing the issue.

How the error is presented depends on the integration:

* AI clients display the error message as part of a failed tool call.
* Direct HTTP integrations receive an HTTP status code and a JSON response body.

```json
{
  "error": "Rate limit exceeded",
  "reason": "quota_exceeded"
}
```

The `error` field is included in every error response. The `reason` field is included when additional context is required to distinguish between errors that would otherwise produce similar messages.

### Error reference

| Status | Message                                                    | What it means                                                                                                            | What to do                                                                                                  |
| ------ | ---------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------- |
| 400    | `Prompt must be a valid string`                            | The search prompt was missing, empty, or not text.                                                                       | Send a non-empty prompt.                                                                                    |
| 400    | `Only prompt and researchMode are allowed in request body` | The request included fields the tool does not accept.                                                                    | Remove the extra fields.                                                                                    |
| 401    | `Missing x-api-key header`                                 | No credential was sent.                                                                                                  | Check your connector's header configuration. See API Key.                                                   |
| 401    | `Invalid API Key`                                          | The credential was not recognized, is disabled, is for another environment, or does not grant the capability you called. | Verify the key and environment; if both are right, the capability may not be enabled for your organization. |
| 429    | `Rate limit exceeded` (`reason: rate_limit_exceeded`)      | Too many calls in the current minute.                                                                                    | Wait for the window to reset and retry. See Rate Limits.                                                    |
| 429    | `Rate limit exceeded` (`reason: quota_exceeded`)           | Your organization's research allowance is exhausted.                                                                     | Waiting will not help — contact your Nichefire representative. See Quota.                                   |
| 500    | `Failed to parse research output`                          | The research ran but its result could not be assembled.                                                                  | Retry. The quota unit is refunded automatically.                                                            |
| 500    | `Internal server error`                                    | Something failed on our side.                                                                                            | Retry; if it persists, contact your Nichefire representative.                                               |

### A note on 401

A `401 Invalid API Key` response indicates that the request could not be authenticated or authorized. For security reasons, the response does not provide additional details.

If you receive this response, verify the following:

1. The API key is correct and has been copied in full.
2. The API key belongs to the environment being accessed. See [**Environments & Access**](/overview/environments-and-access.md).
3. Your organization has access to the requested capability. See [**Capabilities**](/overview/capabilities.md).

### What is never charged

A failed call does not quietly cost you research:

* **Rejected before running** — authentication failures, validation errors, rate limits, and exhausted quota consume nothing.
* **Failed while running** — if research starts and then fails internally, the reserved unit is **refunded** automatically.

The one case that does consume a unit is a search that runs successfully and finds nothing. That is not an error: it returns `200` with an empty result set and an explanation of why. See [`execute_search`](/tools/firesearch/execute-search.md).

### Errors in an AI client

Most clients show the message text and let the assistant decide what to do — often retrying or rephrasing. Two things to know:

* The assistant may not distinguish the two 429s on its own. If it keeps retrying without success, ask it to check usage; [`get_usage`](/tools/get-usage.md) is free and always available, even while you are limited.
* If a tool you expect is missing entirely rather than failing, that is not an error — it means your organization is not entitled to it, so the client never lists it.