Error Handling - SMB Sales Boost API

All errors follow a consistent format with an error code and a human-readable message. Validation errors (400 validation_error, or 400 invalid_request from POST /api/v1/enrichments) can also include a details array with one entry per problem, each with a path (the field, as an array of keys such as ["status"]) and a message.

Error Response Format

{
  "error": "bad_request",
  "message": "No valid fields provided. Allowed: firstName, lastName, companyName, companyWebsite"
}

HTTP Status Codes

Status	Meaning
200	OK - Request succeeded
201	Created - Resource created successfully
202	Accepted - a long-running request is still running in the background: poll `GET /api/v1/jobs/{jobId}` (see Long-Running Requests), which then returns exactly the original response
400	Bad Request - Invalid parameters or missing required fields
401	Unauthorized - Invalid or missing API key
402	Payment Required - insufficient_credits: lead searches and exports are capped at your spendable balance, so they return it only when a concurrent request spent the balance first; POST /api/v1/integrations/:id/push-lead returns it whenever a lead that is new to you cannot be paid from your balance or overage budget. Also a declined card on a purchase
403	Forbidden - API access not available on your plan
404	Not Found - Resource does not exist (`job_not_found` on `GET /api/v1/jobs/{jobId}`: an unknown id, a job that finished more than about a day ago, or a job a server restart interrupted; check what it already did before running anything again)
409	Conflict - the request conflicts with the current state (for example integration_exists, integration_limit, conflict when an integration changed while your update was being applied, or a plan change still in progress). On long-running requests also `idempotency_key_reused` (the Idempotency-Key was already used with a different request) and, on the email schedule trigger, `schedule_run_in_progress` (its regular run is sending it right now; nothing was sent)
429	Too Many Requests - Rate limit exceeded, or lead_query_capacity_busy (tell them apart by the body's error field; both carry the X-RateLimit-* headers); retry after the Retry-After header. Long-running requests can also answer `job_capacity_busy` (too many running at once, Retry-After: 30), and GET /api/v1/leads and POST /api/v1/leads/export `charge_in_progress` (another export, search or push of your account is still recording its charge, Retry-After: 30); nothing was charged or sent
410	Gone - `job_result_expired`: the long-running request finished, but its answer is no longer kept (answered for about a day, then 404 `job_not_found`); the message says where to look, so do not simply repeat the request
500	Internal Server Error - Something went wrong on our end (`job_timeout` when a long-running request ran past its time limit)
502	Bad Gateway - provider_error: a connected CRM's API failed (integration field and pipeline endpoints)
503	Service Unavailable - temporary; retry after the Retry-After header (except provider_unavailable on integration endpoints, which has no Retry-After and is not temporary). Includes `schema_types_warming` on `GET /api/v1/leads/other/schema-types` right after a server restart (Retry-After: 60)

Long-Running Requests

Exports, schedule triggers, category suggestions and the three Lead Export History POST endpoints can answer 202 Accepted with a jobId and finish in the background. See Long-Running Requests for polling GET /api/v1/jobs/{jobId}, Idempotency-Key retries, limits and how long results are kept.

API Documentation Sections

View Full API Documentation

Ready to Find Your Next Customers? Get access to growing local business leads updated every 5 minutes. See plans starting at $49/mo →