How to troubleshoot a request

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. 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.

Getting started

Use cases

Jolts data

Best practices

How to troubleshoot a request

First, identify the outcome

Fix the reported problem

Retry without starting duplicate work

Check MCP separately

Verify the recovery

​First, identify the outcome

​Fix the reported problem

​Retry without starting duplicate work

​Check MCP separately

​Verify the recovery

First, identify the outcome

Fix the reported problem

Retry without starting duplicate work

Check MCP separately

Verify the recovery