Skip to main content

DocsREST API and MCP server

API errors and status codes

Endpoints, auth and live samples for Audience Builder, Connect Data and CRM sync.

Base URLhttps://us-farmvision-new-api.onrender.com

Reference

Errors & status codes

Errors use standard HTTP status codes and the same JSON envelope as successful responses.
StatusMeaning
400The body or query is invalid: it could not be parsed, or a field fails validation (the body names the field).
401The credential is missing, invalid, revoked or expired.
402The route needs an active paid plan, or the plan's credits are used up.
403The credential is valid but not allowed here: a session-only route, a missing CSRF token on a browser write, or a paid MCP plugin on a Free account.
404The upload, run, job or path does not exist.
409A conflict, such as a duplicate upload name, a job start still settling, or a plan change already under way.
413The request body is larger than the route accepts.
415The request body was sent compressed. Send plain JSON.
422The column mapping is incomplete (MAPPING_COMBO_INCOMPLETE).
429A per-minute, hourly or daily limit is reached. Wait for Retry-After, then retry.
500Something failed on GTM Scoop's side. code is TIMEOUT, NETWORK or INTERNAL; the first two are worth retrying.
502A service GTM Scoop depends on (CRM, tool, AI) failed. Retry reads later.
503Search is busy after a 20-second queue, or a service is briefly unavailable. Retry with backoff.
Error shape
{
  "success": false,
  "message": "Not authorized, no token"
}

Which errors to retry

  • 429: wait for the number of seconds in Retry-After when it is sent, otherwise back off 1, 2, 4 seconds, then try again. When the message says daily, stop: a daily limit only clears at midnight (server time).
  • 503: the search queue was full for 20 seconds, or a service is briefly unavailable. Retry with backoff.
  • 500 with code TIMEOUT or NETWORK: retry reads and counts. INTERNAL is worth one retry, then report it.
  • 502: a service GTM Scoop depends on failed. Retry reads such as /ai-criteria. Before retrying a send to a CRM or tool, check whether the first one landed, so records are not sent twice.
  • Any other 4xx: fix the request. Retrying it unchanged gets the same answer.

Starting a job is safe to repeat: a second enrichment start returns the job already running, with 200 instead of 201, and is never charged twice.

Error codes

CodeStatusMeaning
TIMEOUT500A dependency was too slow. Retry.
NETWORK500A dependency could not be reached. Retry in a moment.
INTERNAL500Something else failed on GTM Scoop's side.
AI_RATE_LIMIT429Too many AI requests this minute, such as /ai-criteria.
AI_DAILY_LIMIT429Today's AI requests are used up.
GTM_SCOOP_RATE_LIMIT429A per-account budget for a route family, such as job starts or uploads an hour, is used up.
MAPPING_COMBO_INCOMPLETE422The mapping has no column set a match can use: company data needs a phone or an email plus an address with ZIP. The answer lists what is missing.

Limit and credit messages

StatusMessageWhat happened
429Too many requests for this account. Slow down and try again in a minute.More than 300 requests in a minute from one account.
429Too many requests, please try again later. (plain text)The per-IP limit (120 a minute), or your plan's per-minute limit on the audience search routes.
429Daily MCP limit reached (… on the … plan). It resets at midnight…The key's daily limit for your plan. API calls count toward it too.
402You've used all of this period's enrichment credits…Enrichment credits (200 on Starter, 500 on Growth) are used up until they renew.
402You've used all of this period's account credits…The monthly record allowance for AI analysis and purchases is used up.
402Choose the $299 or $899 Navigator plan to run enrichment.Enrichment and AI analysis need a paid plan.
402The last payment for your Navigator plan didn't go through…Code PAYMENT_PAST_DUE: the subscription's last payment failed. Update the payment method in the web app.

Retry with backoff

These helpers make one call, retry 429 and 503 answers, read a plain-text body without failing, and return data or raise with the message. The other guides' examples use them.

Python
import os
import time
import requests

BASE_URL = "https://us-farmvision-new-api.onrender.com"
HEADERS = {"Authorization": f"Bearer {os.environ['GTMSCOOP_API_KEY']}"}
RETRY_STATUSES = {429, 503}


def call(method, path, body=None, attempts=4):
    """One GTM Scoop API call: retries rate limits and busy answers, returns data."""
    for attempt in range(attempts):
        res = requests.request(method, BASE_URL + path, json=body, headers=HEADERS, timeout=60)
        if res.status_code not in RETRY_STATUSES or attempt == attempts - 1:
            break
        # Retry-After is in seconds; fall back to 1, 2, 4... when it is absent.
        time.sleep(float(res.headers.get("Retry-After") or 2 ** attempt))
    try:
        payload = res.json()
    except ValueError:  # the per-IP and per-minute search limits answer 429 in plain text
        payload = {"success": False, "message": res.text}
    if not payload.get("success"):
        raise RuntimeError(f"{res.status_code}: {payload.get('message')}")
    return payload["data"]


print(call("POST", "/api/v1/business-search/count", {"filters": {"states": ["Texas"]}})["count"])
Node.js
// Node.js 18 or later (fetch is built in). Save as gtmscoop.mjs: top-level await needs an ES module.
const BASE_URL = "https://us-farmvision-new-api.onrender.com";
const HEADERS = {
  Authorization: `Bearer ${process.env.GTMSCOOP_API_KEY}`,
  "Content-Type": "application/json",
};
const RETRY_STATUSES = new Set([429, 503]);

async function call(method, path, body, attempts = 4) {
  let res;
  for (let attempt = 0; attempt < attempts; attempt++) {
    res = await fetch(BASE_URL + path, {
      method,
      headers: HEADERS,
      body: body === undefined ? undefined : JSON.stringify(body),
    });
    if (!RETRY_STATUSES.has(res.status) || attempt === attempts - 1) break;
    // Retry-After is in seconds; fall back to 1, 2, 4... when it is absent.
    const wait = Number(res.headers.get("retry-after")) || 2 ** attempt;
    await new Promise((resolve) => setTimeout(resolve, wait * 1000));
  }
  // The per-IP and per-minute search limits answer 429 in plain text, not JSON.
  const text = await res.text();
  let payload;
  try {
    payload = JSON.parse(text);
  } catch {
    payload = { success: false, message: text };
  }
  if (!payload.success) throw new Error(`${res.status}: ${payload.message}`);
  return payload.data;
}

const { count } = await call("POST", "/api/v1/business-search/count", {
  filters: { states: ["Texas"] },
});
console.log(count);

Related

Cookies on GTM Scoop

Essential cookies keep you signed in and the site secure, and are always on. Optional cookies (Google Analytics) help us understand how the site is used. They are on by default, except in the EU/EEA, the UK and Switzerland, where they stay off until you choose Accept All Cookies; choose Essential Cookies Only to turn them off. We do not use advertising cookies and we do not sell or share your personal information. The site works the same whichever you choose. We keep a record of your choice with the date, your IP address and the page you were on. Cookie Policy · Privacy Policy