Errors.
Every failure is a JSON body with an error code. Nothing that fails is ever billed.
Error responses always contain an error string, and often more. Validation errors list the acceptable values in valid_modes, valid_providers or supported_modes. Failures that reached an engine carry providers_tried and the request_id to quote at us.
| status | error | remedy |
|---|---|---|
| 401 | invalid_api_key | Pass your key as Authorization: Bearer ms_live_… Mint one in the dashboard. |
| 429 | rate_limited | Over 60 requests per minute on that key. Wait the seconds given in the Retry-After header. |
| 400 | invalid_json | Send a valid JSON body with Content-Type: application/json. |
| 400 | missing_query | Include a non-empty query string (a URL for extract/scrape/similar). |
| 400 | invalid_url | extract, scrape and similar take an http(s) URL that resolves to a public address. Private and link-local hosts are refused. |
| 400 | invalid_mode | Use one of the 13 modes. The response lists them in valid_modes. |
| 400 | unknown_provider | No such engine. The response lists valid_providers; check the spelling. |
| 400 | provider_mode_mismatch | That engine cannot serve that mode. The response lists its supported_modes; drop provider or change mode. |
| 402 | insufficient_credits | Balance will not cover the reservation. Top up at metasearch.sh/dashboard. |
| 502 | provider_error | Every candidate engine failed. Not billed. Retry, or name a different provider. |
| 503 | provider_not_available | The engine you named is switched off or unconfigured. Omit provider, or pick another. |
| 503 | no_provider_for_mode | No configured engine supports that mode right now. Check GET /api/v1/providers. |
| 500 | internal_error | Our fault, not yours. Not billed. Retry; if it persists, send us the request_id. |
When 402 happens
Always before dispatch. Every call reserves the most expensive outcome against your balance first, and if the balance will not cover that reservation the request is refused with 402 and your current balance_usd. Nothing is sent upstream, so the reservation is the only thing that ever touched your money.
When a call is not billed
A 502 or 500 means every candidate engine failed. The reservation is refunded in full and the attempt is logged against your account with its request_id. So is a 200 whose results array is empty: an engine that answers with nothing has not answered, and the refund is the whole reservation.
On a successful call the reservation settles down to what the engine actually cost, and the difference returns to your balance in the same transaction. The billing block in the response reports both the final charge and the balance after it.
Rate limits
Sixty requests per minute per key. Over that you get 429 with a Retry-After header in seconds; the limit is checked before anything is parsed, so a throttled request never costs either of us a provider call.