Skip to main content
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

StatusMeaningWhat to do
200Success—
201CreatedThe resource was created.
400Bad requestA parameter is missing or invalid. Check message.
401UnauthorizedThe API key is missing, malformed, or revoked. See Authentication.
402Payment requiredYour credit balance is too low for the action. Top up in Settings → Credits. See Credits.
403ForbiddenThe key isn’t permitted to access this resource.
404Not foundThe resource doesn’t exist, or isn’t in your workspace.
429Rate limitedYou’ve exceeded the request limit. See Rate limits.
5xxServer errorA problem on our side. Retry with backoff; if it persists, contact support.

​
Handling errors

Check the status code first, then read error.message. Retry only idempotent GET requests on 429 and 5xx, using exponential backoff. Never blindly retry 4xx responses other than 429 — the request needs to change first. 
resp = requests.get(url, headers=headers)
if not resp.ok:
    err = resp.json().get("error", {})
    raise RuntimeError(f"{resp.status_code}: {err.get('message')}")