API reference
API errors
Written and maintained by The ProspectAPIs team
A ProspectAPIs API error is a JSON response with a 4xx or 5xx status and an error string that says what went wrong. Some errors also carry a stable code, and a 402 carries the URL to add credits. A request that fails is never billed: any hold taken for it is refunded when the response closes.
The error body
Every REST error has the same shape. Only error is always present; read code when you need to branch on the cause, because the message text can change.
{
"error": "unknown parameter: rounds",
"code": "INVALID_FILTER"
}| Field | When |
|---|---|
| error | Always. A message you can show or log. |
| code | On validation errors and the watchlist limit, as listed below. |
| message | On a 401 for a missing key and on a 402: what to do next. |
| top_up_url | On a 402: where to add credits. |
| field | On some POST /v1/feedback 400s: the field that failed. |
A 5xx never carries internal detail. The body says only what kind of failure it was, for example Internal server error, and the full detail stays in our logs.
HTTP status codes
| Status | When it happens |
|---|---|
| 400 | Bad input: an unknown query parameter or body field, a malformed id or date, a body that is not valid JSON, or more than one research identifier. The body names the problem. |
| 401 | Missing or invalid API key. Send Authorization: Bearer pa_live_... |
| 402 | Not enough credits for this call. The body carries top_up_url; nothing was charged. |
| 404 | No record, research job or watchlist with that id, a job or watchlist that belongs to another account, or no such route. Never charged. |
| 405 | HEAD on a /v1 data route. Use GET. |
| 409 | Creating a watchlist when the account already has the most active watchlists allowed. Delete one first. |
| 413 | A request body over 100 kB. |
| 429 | Rate limit reached. Wait for the window to pass, then retry; do not retry in a tight loop. |
| 500 | An unexpected server error. The body says only Internal server error; the hold is refunded. |
| 502 | Feedback only: the report could not be delivered. Retry shortly. |
| 503 | A dependency is unavailable (authentication, or a route that is not launched yet, such as research in early access). Retry later. |
| 504 | The request ran past its deadline (45 seconds by default). Not charged. |
Error codes
| Code | Status | Meaning |
|---|---|---|
| INVALID_FILTER | 400 | A GET /v1/funding filter is malformed or out of range. |
| INVALID_INPUT | 400 | A research or watchlist body failed validation. |
| INVALID_ID | 400 | An id in the path is not a UUID (funding and research). |
| WATCHLIST_LIMIT | 409 | The account is at its active watchlist limit. |
402 Payment Required
Out of credits and free records, the API answers before serving anything:
{
"error": "Insufficient credits",
"top_up_url": "https://prospectapis.com/dashboard/credits",
"message": "Out of credits and free records for this month. Top up at https://prospectapis.com/dashboard/credits to continue."
}Which errors to retry
Retry a 429, 502, 503 or 504 after a pause; a per-key 429 tells you how long in Retry-After (the limit is 60 requests a minute per key, see rate limits). Do not retry a 400, 401, 402, 404, 405, 409 or 413 unchanged: fix the request, the key or the balance first. On the hosted MCP server, a failed tool call comes back as a tool result marked isError that carries the HTTP status and the API's own error body. On POST /mcp the door itself answers with a JSON-RPC error: -32001 for a missing or refused key, -32000 for its own rate limit, when it is unavailable or for a method or content type it does not take, -32600 for a batch or an oversized body, -32700 for a body that is not a valid JSON-RPC message and -32603 for an internal error. The keyless POST /mcp/free answers its per-minute limits with a plain HTTP 429 and {"error":"rate_limited"}, and a busy moment with a plain 503; its hourly and daily allowances come back as a tool result marked isError with a sign-up link.
Each operation's own responses are listed on its page in the API reference, and keys are covered in authentication. Create a free account to get a key and try a call. An agent that reads these errors and retries on its own is the setup in researching prospects with an AI agent.