Lead API · Developers
Step 3 of 4

Errors

What an error looks like, what each one means, which problems only warn, and when to retry.

1. Error format

Every lead and marketplace endpoint returns errors in this shape.

403 response 
{
  "statusCode": 403,
  "timestamp": "2026-10-23T09:15:02.118Z",
  "path": "/api/public/v2/leads",
  "message": "This organization is not enabled for provider actions.",
  "code": "CAPABILITY_REQUIRED",
  "capability": "provider"
}
  • message is always text; several validation errors are joined with , .
  • code (and capability) appear only on the organisation errors ORG_INACTIVE and CAPABILITY_REQUIRED.
  • GET /account returns the shorter { "statusCode", "message", "error" } body, or { "code", "message" } for ORG_INACTIVE.

2. Status codes

Status Code Meaning What to do
400 — Invalid request: a missing required field, street or city missing, properties without building, an invalid email, updatedSince missing or older than 30 days, more than 500 IDs or a non-UUID in a bulk request, or a PATCH on a lead not (yet) in READY / READY_NON_EXCLUSIVE — new leads become READY after verification. Fix the request; message says what is wrong.
401 — The key is missing, malformed or unknown, or lacks the permission. Send Authorization: Bearer sk_… with a key for this environment that has the permission.
403 ORG_INACTIVE Your organisation's access is disabled. Refused requests are not replayed later. Contact zolar.
403 CAPABILITY_REQUIRED Your organisation is not a lead provider yet. Production: Become a lead provider on the Welcome screen (or Create Marketplace once onboarded) → Request to be a lead provider; zolar's team will contact you. Demo: the same request is approved automatically.
404 — PATCH: the lead does not exist, or is not in a marketplace you own. Check the lead ID.
409 — Duplicate lead — see below. Don't send it again.
429 — More than 60 requests in the last 60 seconds with this key. Wait, then retry. Spread your requests out.
500 — Something went wrong on our side. Retry later. If it persists, contact us with the time of the request.

Duplicates: a lead is a duplicate when a lead received in the last month has exactly the same first name, last name, email and city — or the same first name, last name, postal code and mobile phone.

Warnings are not errors: a successful create or update lists ignored fields, such as unknown ones, in warnings. Log them and fix your request.

3. Warnings

Warnings are extra information that isn't serious enough to reject the request. The lead is still created (201) or updated (200); the problematic value is ignored and listed in warnings. An empty list means everything was understood.

Example: interest contains a key that doesn't exist (here solar instead of pv).

Request (excerpt) 
"properties": {
  "interest": { "solar": "interestNew" },
  "building": { "type": "residential" }
}
201 response 
{
  "id": "00000000-0000-4000-8000-000000000001",
  "warnings": [
    "Unknown field 'properties.interest.solar' - this value will be ignored"
  ]
}
  • The lead is created, but without that interest. A lead with no valid interest is not shown to installers — so treat this warning as a bug to fix.
  • Unknown fields anywhere in the body produce the same warning.
  • Invalid values in optional building, roof and energy fields (for example building.type or roof.orientation) are ignored with a warning like Invalid type: "castle" (allowed: …) - this value will be ignored.
  • An invalid value for an existing interest key (e.g. "pv": "yes") is an error, not a warning: 400.
  • Log warnings on your side so you notice them.

4. Retries

  • Retry 429 after a pause, not immediately.
  • Retry 5xx with a growing back-off.
  • Don't retry other 4xx unchanged — the same request fails again.
NextGoing live