Errors

HTTP status codes the JobsPipe API returns, and how to handle them.

Errors return a JSON body with an error message:

{ "error": "Rate limit exceeded" }

Status codes

Statuserror messageCauseWhat to do
400Invalid search filters: ...A filter name we do not have, or a value of the wrong type.Read the message; it names the field and, for an unknown name, suggests the real one.
401Unauthorized / Invalid API keyMissing, malformed, or revoked key.Check the Authorization header and key validity.
402Monthly request quota exceededYou are out of credits: this month's allowance, or on Free the one-time 1,000 credits.Wait for your next monthly credits, buy credits, or upgrade. On Free, pick a package.
403Blocked: ...The account is not allowed to use the API.See 403 Forbidden. Retrying the same request will not help.
404company_not_found / Not FoundNo record for the key, or no such route.On a company lookup or a company tech stack, company_not_found lists candidates; pick one. Costs nothing.
429Rate limit exceededToo many requests in one second for your plan, or more searches running at once than your plan allows (the body says which: concurrent_searches).Back off and retry (see below).
502variesThe request could not be completed.Retry.
504variesThe search timed out.Retry; if it persists, narrow your filters.
500Internal Server ErrorUnexpected server error.Retry; contact support if it persists.

See rate limits & plans for the exact per-second and monthly thresholds.

402 Payment Required

A 402 means the account is out of credits. The body says how many credits were included and used, and carries upgrade_url, the billing page sized to your usage. On Free it also carries checkout_url: a one-time link, valid for seven days, that opens Stripe Checkout for the Builder package (25,000 credits a month) for this account with nothing else to fill in. An agent can hand that link to its user as it is. The same link is emailed once when the credits run out.

{
  "error": "Monthly request quota exceeded",
  "message": "...Open checkout_url to buy the Builder package (25,000 credits a month for $49) in one step.",
  "credits_used": 1000,
  "credits_included": 1000,
  "upgrade_url": "https://jobspipe.dev/dashboard/billing?credits=25",
  "checkout_url": "https://api.jobspipe.dev/v1/checkout/start?t=..."
}

Plan limits

A 402 can also mean a plan limit, not spent credits: the Signals (saved searches) a plan holds, or in Prospects the accounts a workspace watches, its lists on the trial and the trial's runs a week. The body keeps error, message and upgrade_url, and adds which product and limit, what is used of what is included, and the plan that lifts it. upgrade_url opens that plan's checkout on the billing page, or the pricing page for Enterprise. Nothing is charged for a refused request.

{
  "error": "Plan limit reached (3 signals). Upgrade to add more.",
  "message": "Plan limit reached (3 signals). Upgrade to add more. Next plan: Builder at $49 a month.",
  "upgrade_url": "https://jobspipe.dev/dashboard/settings/billing?credits=25000",
  "dashboard_url": "https://jobspipe.dev/dashboard/api",
  "product": "api",
  "limit": "saved_searches",
  "used": 3,
  "included": 3,
  "suggested_plan": { "product": "api", "id": "builder", "name": "Builder", "monthly_usd": 49 }
}

limit is one of saved_searches, accounts, lists or runs_per_week; suggested_plan is null when no plan lifts the limit.

403 Forbidden

A 403 uses the same { "error": "..." } shape, and the message says what to do. It is not a rate limit, so retrying does not clear it.

Blocked account

Accounts that break the signup rules, for example accounts registered with a disposable email address, are refused on every authenticated request (API key, dashboard and MCP):

{
  "error": "Blocked: this account was created with a disposable email address, which JobsPipe does not allow. Sign up again with your own work email, or book a call at https://jobspipe.dev/book to get verified."
}

Sign up again with your own work email, or book a call to get the account verified.

Reading a 400

Unknown filter names are rejected, not ignored. The message names every unknown key and suggests the closest real one:

{
  "error": "Invalid search filters: unknown filters: 'query', 'location'. Did you mean query -> job_title_or, location -> job_location_or?"
}

A value a filter does not accept is reported the same way, with the value you most likely meant when one is clear. A value we do not track (for example an employer type of government) lists the allowed values without a guess:

{
  "error": "Invalid search filters: employer_type_not.0: Invalid enum value. Expected 'employer' | 'agency' | 'broker', received 'staffing'. Did you mean 'agency'?"
}

A body that is not usable JSON says why: it is empty, it has a trailing comma or single quotes (with the line and column), or the filters are wrapped in a string field instead of sent as the JSON object itself.

A cursor from an older version of search is refused the same way: Invalid search filters: cursor is from an older version of the search and can no longer be continued; repeat the search without cursor to start again from the first page. Send the search again without cursor.

Numbers and booleans sent as strings are accepted ("posted_at_max_age_days": "10" means 10). An explicit null is treated as an absent field.

Handling 429 with backoff

When you hit the per-second limit, pause and retry with exponential backoff. A 429 whose body carries concurrent_searches means that many of your searches are already running (3 on Free and Seeker, 4 on Builder and Growth, 6 on Scale and Business): wait for one of them to finish (the body's retry_after_seconds is 2) rather than retrying at once.

import time, requests

def search_with_retry(body, headers, tries=4):
    for i in range(tries):
        resp = requests.post(
            "https://api.jobspipe.dev/v1/jobs/search", headers=headers, json=body
        )
        if resp.status_code != 429:
            resp.raise_for_status()
            return resp.json()
        time.sleep(0.25 * (2 ** i))
    raise RuntimeError("rate limited")
async function searchWithRetry(body, headers, tries = 4) {
  for (let i = 0; i < tries; i++) {
    const resp = await fetch("https://api.jobspipe.dev/v1/jobs/search", {
      method: "POST",
      headers,
      body: JSON.stringify(body),
    });
    if (resp.status !== 429) return resp.json();
    await new Promise((r) => setTimeout(r, 250 * 2 ** i));
  }
  throw new Error("rate limited");
}

Backing off does not help with 402 (out of credits) or 403 (blocked account). For a 402, wait for your next monthly credits, buy credits or upgrade; on Free, pick a package. For a 403, see 403 Forbidden.

On this page