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

# Errors

> HTTP errors from the endpoint and error codes inside result envelopes.

## HTTP errors

These stop a request before any tool runs. Clients handle most of them.

| Status | Code | Meaning | Fix |
| - | - | - | - |
| `401` | `session_expired`, `session_revoked` | Missing, expired or revoked token. `WWW-Authenticate` carries `error="invalid_token"` and the OAuth metadata URL. | The client refreshes or signs in again. |
| `402` | `entitlement_required` | The account has no active plan. | Buy or renew a plan. |
| `403` | `upgrade_required` | The account has no active Fincept Exclusive plan. | Subscribe to any Exclusive plan. |
| `429` | `rate_limited` | More than 120 requests a minute. `Retry-After` gives the wait. | Back off and retry. |

## Envelope errors

A tool that runs but cannot answer returns an envelope with `status: "error"`, `isError: true` and one of these codes in `error.code`.

| Code | Meaning |
| - | - |
| `validation_failed` | Arguments do not match the tool's schema, or a `$fincept` reference failed. The message names the field. |
| `upgrade_required` | This tool, or an option of it, needs a feature or capability the plan does not include. |
| `quota_exceeded` | A plan quota is reached, such as the number of watchlists or portfolios. |
| `insufficient_credits` | Not enough credits for a paid tool. |
| `spend_cap_reached` | The daily credit cap or the hourly cap for this action is reached. |
| `not_found` | The item does not exist or belongs to another account, or a stored result expired. |
| `timeout` | The call ran past its time limit. |
| `busy` | The Fincept engine behind the tool (Stats, Forecast, Volatility, Pricing or any other) has no free worker, or Fincept Scanner is pacing its requests to the market data source. Retry after `details.retry_after_s` seconds when given, else in a few seconds. |
| `model_failed` | An engine computation (a model fit, an optimisation, a forecast) failed on this data. The hint suggests what to change. |
| `unavailable` | A Fincept service could not be reached. Retry later. |

Other codes come straight from the service that refused, with a `message` and often a `hint`; agents should read and relay them.

## Unknown tools

Calling a name the catalog does not have is a JSON-RPC error (`unknown tool`), not an envelope. Use `fincept_search_tools` to find the right name.


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