Reference
Errors & status codes
| Status | Meaning |
|---|---|
| 400 | The body or query is invalid: it could not be parsed, or a field fails validation (the body names the field). |
| 401 | The credential is missing, invalid, revoked or expired. |
| 402 | The route needs an active paid plan, or the plan's credits are used up. |
| 403 | The 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. |
| 404 | The upload, run, job or path does not exist. |
| 409 | A conflict, such as a duplicate upload name, a job start still settling, or a plan change already under way. |
| 413 | The request body is larger than the route accepts. |
| 415 | The request body was sent compressed. Send plain JSON. |
| 422 | The column mapping is incomplete (MAPPING_COMBO_INCOMPLETE). |
| 429 | A per-minute, hourly or daily limit is reached. Wait for Retry-After, then retry. |
| 500 | Something failed on GTM Scoop's side. code is TIMEOUT, NETWORK or INTERNAL; the first two are worth retrying. |
| 502 | A service GTM Scoop depends on (CRM, tool, AI) failed. Retry reads later. |
| 503 | Search is busy after a 20-second queue, or a service is briefly unavailable. Retry with backoff. |
{
"success": false,
"message": "Not authorized, no token"
}Which errors to retry
- 429: wait for the number of seconds in
Retry-Afterwhen 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
codeTIMEOUTorNETWORK: retry reads and counts.INTERNALis 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
| Code | Status | Meaning |
|---|---|---|
TIMEOUT | 500 | A dependency was too slow. Retry. |
NETWORK | 500 | A dependency could not be reached. Retry in a moment. |
INTERNAL | 500 | Something else failed on GTM Scoop's side. |
AI_RATE_LIMIT | 429 | Too many AI requests this minute, such as /ai-criteria. |
AI_DAILY_LIMIT | 429 | Today's AI requests are used up. |
GTM_SCOOP_RATE_LIMIT | 429 | A per-account budget for a route family, such as job starts or uploads an hour, is used up. |
MAPPING_COMBO_INCOMPLETE | 422 | The 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
| Status | Message | What happened |
|---|---|---|
| 429 | Too many requests for this account. Slow down and try again in a minute. | More than 300 requests in a minute from one account. |
| 429 | Too 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. |
| 429 | Daily MCP limit reached (… on the … plan). It resets at midnight… | The key's daily limit for your plan. API calls count toward it too. |
| 402 | You've used all of this period's enrichment credits… | Enrichment credits (200 on Starter, 500 on Growth) are used up until they renew. |
| 402 | You've used all of this period's account credits… | The monthly record allowance for AI analysis and purchases is used up. |
| 402 | Choose the $299 or $899 Navigator plan to run enrichment. | Enrichment and AI analysis need a paid plan. |
| 402 | The 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.
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 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);