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

# How to troubleshoot a request

> Tell a pending search, an empty result, and a failed request apart.

## First, identify the outcome

For HTTP, check the status code and response body. For MCP, check `result.isError` and
`result.structuredContent.error` as well: HTTP success does not prove tool success.

| What you see                         | What it means                  | Next step                                                                              |
| ------------------------------------ | ------------------------------ | -------------------------------------------------------------------------------------- |
| `202` with `pending` or `processing` | The operation has not finished | Keep its `usage.id`; poll `GET /api/usages/{id}` or MCP `get_usage` after a short wait |
| Completed `companies: []`            | No companies were delivered    | Review coverage and filters; do not call it a system failure or proof of no demand     |
| An `error` object                    | The operation did not succeed  | Follow the code below; do not treat it as an empty result                              |
| `next_cursor` is not null            | Another page is available      | Keep query, filters, and limit unchanged; send the cursor with a new request key       |

## Fix the reported problem

| Error or status                                                    | Meaning                                                | Action                                                                                                            |
| ------------------------------------------------------------------ | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------- |
| HTTP `401`                                                         | The credential was rejected                            | Check the application host and bearer header. Replace a revoked key. Never paste it into chat                     |
| `subscription_required`                                            | The account lacks the required subscription access     | Check the account's subscription; creating another API key does not activate it                                   |
| `invalid_search`                                                   | One or more inputs are invalid                         | Read the message and the endpoint's parameter reference. Correct the input before retrying                        |
| `unsupported_request`                                              | Company-search planning cannot support the request     | Narrow the question to the documented coverage. Do not assume a broader prompt unlocks new data                   |
| `invalid_cursor`                                                   | The continuation token cannot be used for this search  | Start again without the cursor and with a new request key                                                         |
| `idempotency_conflict`                                             | The request key belongs to different inputs            | Use the original inputs to retry that operation, or a new key for intentionally new work                          |
| `result_limit_reached`                                             | The requested page exceeds the plan's per-search limit | Lower `limit` to the permitted page size                                                                          |
| `request_limit_reached` or `delivery_limit_reached`                | The subscription's allowance is exhausted              | Check `GET /api/usage` or MCP `get_usage` without an ID; follow `retry_at` or `retry_after_seconds` when supplied |
| `company_not_found` or `observation_not_found`                     | No currently deliverable record was found for that ID  | Use an ID returned by a current search; records can lose eligible evidence                                        |
| `usage_not_found`                                                  | The operation is not available to this account         | Check the ID and the account owning the key                                                                       |
| `planning_unavailable`, `retrieval_unavailable`, or `invalid_plan` | Jolts could not prepare or perform the search          | Keep the operation ID. The same key replays its terminal result; a deliberate new attempt needs a new key         |
| `usage_expired` or `usage_failed`                                  | The operation ended without completing successfully    | Do not keep polling indefinitely. Keep its ID for support and use a new key only to intentionally retry           |

## Retry without starting duplicate work

If the network disconnects before a response arrives, the search may still have started. Retry the
same request with its original key, or retrieve the operation if you already have its ID. Do not
switch keys simply because the browser or client stopped waiting.

Once an operation is terminal, replaying its key does not restart it. Correct invalid inputs or
wait for the reported allowance reset before deliberately starting new work. API keys on one
subscription share limits; rotating keys does not create extra allowance.

## Check MCP separately

If the assistant cannot list tools, follow the [MCP connection checks](/mcp). If it can list tools
but a search fails, the transport may be working: inspect the tool's structured error, subscription,
and request key. Connecting to Mintlify's documentation-search MCP does not connect the assistant
to Jolts' authenticated company-data tools.

## Verify the recovery

Repeat a corrected request and inspect the full result. For background work, continue until the
operation finishes, fails, or expires. Check the evidence and coverage before using a returned
company in a sales decision. If it still fails, share the operation ID and error code with support,
not credentials or an unredacted request dump.