Lead API · Developers
Step 4 of 5

Errors

What an error looks like, what each one means, and when to retry.

1. Error format

Errors are JSON with the status code and a message.

400 response 
{
  "statusCode": 400,
  "message": [
    "priceType must be one of the following values: EXCLUSIVE, NONEXCLUSIVE"
  ],
  "error": "Bad Request"
}
  • message is a list for request validation errors, otherwise text.
  • Organisation errors carry a code instead: { "code": "CAPABILITY_REQUIRED", "capability": "buyer", "message": "…" }.
  • A reached buy limit adds periodEnd; a rejected webhook template adds an errors list.

2. Status codes

Status Code / message Meaning What to do
400 — Invalid request: filterId, priceType or price missing on buy, price or reward below 0, an unknown status, an updatedSince that isn't ISO 8601, or limit outside 1–100. Fix the request; message lists each problem.
400 SUBCONTRACT_EXCLUSIVE_ONLY, SUBCONTRACT_REWARD_MISSING A subcontract lead (leadPhase: SUBCONTRACT). Its reward isn't exposed through the API yet, so subcontract leads can't be bought through the API. Contact zolar.
400 — Webhook rejected: invalid URL, reserved or repeated header, broken bodyTemplate, or the 20-endpoint limit reached. Fix the endpoint; a template error lists each problem.
401 — The key is missing, malformed or unknown, or lacks the permission. Send Authorization: Bearer sk_… with a key that has the permission.
403 ORG_INACTIVE Your organisation's access is disabled. Contact zolar.
403 CAPABILITY_REQUIRED Your organisation is not a lead buyer (this applies to reads and status updates too). Request lead access in the portal; on Demo, finish the onboarding wizard.
403 — On buy: your organisation hasn't accepted this marketplace's terms, or has no access to it. Accept the marketplace's terms in the portal.
404 — The lead, lead offer or webhook endpoint does not exist or isn't yours. Check the ID — buying takes the lead ID, updating takes the leadOfferId.
409 PRICE_MISMATCH The price changed since you read it. Fetch the opportunity again and retry with the new price.
409 REWARD_MISMATCH Subcontract lead: the reward you sent doesn't match. Contact zolar (see the subcontract row above).
409 User already claimed this lead Your organisation already bought this lead. Don't retry; find it in GET /leads.
409 Purchase limit exceeded … The marketplace's buy limit is used up. Wait until periodEnd.
409 Lead is not available … The lead can't be bought for this priceType any more, for example someone bought it exclusively. Skip this lead.
409 Lead is not in the correct status The lead is no longer for sale. Skip this lead.
429 — More than 60 requests in the last 60 seconds with this key. Wait, then retry. Spread your requests out. The body has no error field.
500 — Something went wrong on our side. A database error returns { "statusCode", "message", "timestamp" }. Retry later with back-off. If it persists, contact us with the time of the request.

Not errors: an empty GET /opportunities or GET /leads returns rows: [], and an updatedSince older than 90 days is treated as 90 days ago.

3. Retries

  • Retry 429 after a pause, not immediately.
  • Retry 5xx with a growing back-off.
  • Don't retry other 4xx unchanged; on a price change, re-read the opportunity first.
NextGoing live