Errors

The Leadey API uses conventional HTTP status codes. A 2xx means success, a 4xx means the request was rejected (and usually tells you how to fix it), and a 5xx means something went wrong on our side.

Error shape

Every error returns the same JSON envelope:

{
  "error": {
    "message": "A human-readable description of what went wrong.",
    "details": null
  }
}

message — a clear, actionable description.
details — optional structured context (an object, array, or string), or null.

Status codes

Status	Meaning	What to do
`200`	Success	—
`201`	Created	The resource was created.
`204`	No content	A `DELETE` succeeded. There is no response body.
`400`	Bad request	A field is missing or invalid, or the key has no member to attribute writes to. Check `message`.
`401`	Unauthorized	The API key is missing, malformed, or revoked. See Authentication.
`402`	Payment required	Your credit balance is too low for the action. Top up in Settings → Credits. See Credits.
`403`	Forbidden	The key is read only, or your workspace can’t currently write. See below.
`404`	Not found	The resource doesn’t exist, or isn’t in your workspace.
`429`	Rate limited	You’ve exceeded the request limit. See Rate limits.
`5xx`	Server error	A problem on our side. Retry with backoff; if it persists, contact support.

Writes and `403`

A 403 on a write means one of two things. The key is read only. Access is chosen when a key is created and can’t be changed afterwards. Create a key with read and write access in Settings → API Keys.

{
  "error": {
    "message": "This API key is read-only. Create a key with write access in Settings → API Keys.",
    "details": null
  }
}

The workspace can’t write. If the trial has expired, an invoice is long overdue, or the subscription was cancelled, writes are blocked through the API just as they are in the Cockpit. These errors carry a code in details so you can branch on them:

{
  "error": {
    "message": "Your free trial has expired. Please upgrade to continue.",
    "details": { "code": "TRIAL_EXPIRED" }
  }
}

Code	Meaning
`PAYMENT_SETUP_REQUIRED`	No payment method on the workspace yet.
`TRIAL_EXPIRED`	The free trial has ended.
`PAYMENT_REQUIRED`	An invoice has been overdue for more than 14 days.
`SUBSCRIPTION_CANCELLED`	The subscription was cancelled.

Reads keep working in every one of these cases, so a reporting integration is never taken down by a billing problem.

Handling errors

Check the status code first, then read error.message. Retry only idempotent requests on 429 and 5xx, using exponential backoff. Never blindly retry 4xx responses other than 429 — the request needs to change first. Every GET is safe to retry, and so is POST /leads: leads are deduplicated by the person they resolve to, so a retry returns the existing lead rather than creating a second one. See Writing data.

resp = requests.get(url, headers=headers)
if not resp.ok:
    err = resp.json().get("error", {})
    raise RuntimeError(f"{resp.status_code}: {err.get('message')}")

Getting started

Core concepts

Using the API

Webhooks

Error shape

Status codes

Writes and `403`

Handling errors

​Error shape

​Status codes

​Writes and 403

​Handling errors

Error shape

Status codes

Writes and `403`

Handling errors