Search API Errors and Limits

PacketStream Search API error codes and what to do about each, which requests are billed, rate limits, timeouts, and how to retry safely.

Error format

Errors are JSON with a stable code and a readable message:

{
  "request_id": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5f",
  "error": {
    "code": "unsupported_option",
    "message": "country is not supported for type scholar"
  }
}

Handle errors by code. Messages explain the problem but can change. Every error also carries the request ID in the X-Request-Id header.

Error codes

Code	HTTP	Meaning	Does retrying help?
`invalid_request`	400	The JSON or query string is malformed, or a field is missing, unknown, repeated, mistyped, or out of range. The message names the field.	No. Fix the request.
`unsupported_option`	400	The type does not accept an option you sent, or no search source can serve this combination right now.	No. Remove the option or change the type.
`unauthorized`	401	The API key is missing, malformed, revoked, or unknown.	No. Check the key.
`insufficient_balance`	402	Your balance is below the cost of one search ($0.0025), or other requests spent it while this one ran.	After you add funds.
`method_not_allowed`	405	The path does not accept this HTTP method. The `Allow` header lists the methods it does accept.	No. Use a listed method.
`request_too_large`	413	The POST body or GET query string is over 4,096 bytes, or a batch body is over 16 KiB.	No. Shorten the request.
`rate_limited`	429	More than 5 requests per second, with bursts of 10, for this key. Search, batch items, fetch, and MCP tool calls share the limit.	Yes, after the `Retry-After` header.
`internal_error`	500	An unexpected server error. Rarely, the search was charged just before the error.	Retry once. If a duplicate charge matters, check your balance with `GET /v1/account` first.
`search_unavailable`	503	No search source returned a usable answer.	Yes, with backoff.
`capacity_exceeded`	503	Search capacity is temporarily full.	Yes, with backoff.
`search_disabled`	503	Search is temporarily turned off.	Yes, later.

The Fetch API has its own codes. For errors inside MCP tool calls, see the MCP reference.

Billing

Only successful searches are billed, at $0.0025 each for every type and option.
Errors are free, with one rare exception: a 500 internal_error can follow a charge that went through just before the failure, for example when a database connection drops while the charge is recorded. Your balance, from GET /v1/account or the dashboard, is authoritative. The dashboard’s recent requests can show such a request as not charged.
A successful search that finds no results is billed.
A batch is billed for each successful item.
The MCP server bills each successful web_search or web_fetch call. Listing tools is free.

Rate limits

Each key may send 5 requests per second, with bursts of up to 10. Searches, batch items, fetch requests, and MCP tool calls share this limit. GET /v1/account does not count against it.
Requests rejected during validation do not use the limit.
Over the limit, the API returns 429 rate_limited with Retry-After: 1.
The limit is tracked on each API server, so X-RateLimit-Remaining is approximate and the effective limit can be somewhat higher. Do not depend on going over the nominal limit.

Timeouts

The server finishes or gives up on every request within 25 seconds. Most searches take a few seconds.
Use a client timeout of at least 35 seconds. If your client gives up first, the search can still finish and be billed. Check the dashboard’s recent requests before you retry an expensive job.

Retrying safely

Retry a 429 after the Retry-After delay.
Retry a 503 with exponential backoff and some random jitter.
Retry a 500 at most once.
Do not retry a 400, 401, 402, 405, or 413 until you change the request, the key, or your balance.