Error codes

Full list of HTTP status codes returned by the TMaps API, with their meaning, typical cause and response body format.

All errors returned by the TMaps API follow a common JSON format and use standard HTTP codes. This page lists the codes you may encounter and what they mean.

Error format

Every error response has a minimal JSON body, encoded as UTF-8:

{
  "error": "missing api_key"
}

The error field contains a short English message useful for debugging. This message may evolve over time: don't parse it for business logic — rely on the HTTP status code.

HTTP codes

HTTP	Meaning	Typical cause	Response body
400	Bad request	Required parameter missing or malformed	`{"error":"missing required param: q"}`
401	Invalid API key	api_key missing, disabled or revoked	`{"error":"missing api_key"}`
403	Domain not authorized	Origin / Referer not whitelisted, or HTTP request	`{"error":"domain not authorized"}`
404	Resource not found	Endpoint or identifier does not exist	`{"error":"not found"}`
429	Too many requests	Burst protection at the infrastructure level (no quota by default)	`{"error":"rate limited"}`
500	Server error	Internal incident — retry after a few seconds	`{"error":"internal error"}`

No application-level rate limit

The TMaps API does not enforce any per-key quota or rate limit. The 429 code only appears when burst protection kicks in at the infrastructure layer (occasional spike) — it's rare in normal usage and resolved by a simple retry with backoff.

Handling errors client-side

Recognize an authentication error

Codes 401 and 403 are configuration errors, not usage errors: retrying won't help. Check instead:

401: is the key set? Active in the console?
403: is the calling domain in the authorized domains list? If the call is server-side (no Origin), the 403 should not happen.

Retry strategy

4xx: never retry automatically (except 429).
429: retry with exponential backoff (1 s, 2 s, 4 s) — max 3 attempts.
5xx: retry with exponential backoff — max 3 attempts.

Example — fetch wrapper with retry

async function tmapsFetch(url, options = {}, retries = 3) {
  for (let i = 0; i < retries; i++) {
    const res = await fetch(url, options);

    // No error → return
    if (res.ok) return res.json();

    // 4xx (except 429) → permanent error
    if (res.status >= 400 && res.status < 500 && res.status !== 429) {
      const body = await res.json().catch(() => ({}));
      throw new Error(`TMaps ${res.status} — ${body.error ?? 'unknown'}`);
    }

    // 429 or 5xx → exponential backoff
    await new Promise((r) => setTimeout(r, 2 ** i * 1000));
  }
  throw new Error('TMaps: max retries reached');
}