Errors & rate limits
Every error code the REST API and the MCP server return, what to do about each, and the limits on keys and calls.
One error body
Every REST error has the same body, so branch on error.code, not on the message:
{"error":{"code":"credits_exhausted","message":"This call needs 12 credits; you have 5. …"}}A call that returns an error is not charged.
Error codes
| HTTP | error.code | What to do |
|---|---|---|
400 | invalid_request | Bad input or malformed JSON. The message names the field. |
400 | invalid_domain · blocked_host · engine_unavailable | The domain does not look like example.com, is not a public host, or you asked for an engine this server does not have (the message lists the ones it has). |
401 | unauthorized | No key was sent. Add the Authorization header. |
401 | invalid_api_key | The key was sent but is wrong or has been revoked. Create a new one on your account page. |
402 | credits_exhausted | Not enough credits for this call. The message says how many it needs and links to upgrade or buy a pack. |
404 | not_found | This tool is not available on this server. GET /api/v1/me lists what is. |
415 | unsupported_media_type | A POST without content-type: application/json. |
429 | rate_limited | More than 1,000 requests today on this key. Wait the number of seconds in the Retry-After header. |
429 | spend_ceiling | The daily safety limit on checks for your account was reached. Try again tomorrow. |
502 | upstream_failed · fetch_failed · site_unreachable · suggest_failed | A site we had to fetch, or a data source behind the tool, failed. Safe to retry. |
502 | not_configured · no_engines | The tool is not set up on this server. Retrying will not help; tell us. |
500 | internal | Our bug. Retry once, then email us. |
Errors over MCP
A bad or missing key is refused before any tool runs: HTTP 401 with a JSON-RPC error whose data.code is invalid_api_key. Over 1,000 requests a day on one key gets HTTP 429, data.code rate_limited, and a Retry-After header.
A tool that fails comes back as a normal tool result with isError: true and one line of text, code: message, using the same codes as the REST API. For example:
credits_exhausted: This call needs 12 credits; you have 5. Your free plan gives 200 credits a month — upgrade or buy a pack at https://geondex.com/account.A call that fails is not charged.
A raw HTTP call to https://geondex.com/mcp whose accept header does not list both application/json and text/event-stream gets a 406. See Any other client, or raw HTTP.
Limits
- Every tool returns in under 25 seconds.
- An engine that does not answer within 20 seconds is reported as timed out and is not charged.
- Keys are limited to 1,000 requests a day. The
429carries aRetry-Afterheader. - A daily safety limit on checks protects your account from a runaway loop (
spend_ceiling). - When credits run out you get a clear error with a link to upgrade or buy a pack; nothing is queued and nothing is charged automatically. Prices are on /pricing.