Errors

Error codes and how to handle them.

The Leonar API uses standard HTTP status codes and returns structured error responses.

Error format

{
  "error": {
    "code": "validation_error",
    "message": "email: Invalid email format"
  }
}

Error codes

Code	HTTP status	Description
validation_error	400	Invalid request data
invalid_api_key	401	Missing or invalid API key
insufficient_credits	402	The workspace does not have enough credits to cover this request. Returned by POST /sourcing/advanced/profiles/search when the sourcing credit balance is empty.
insufficient_scope	403	API key lacks the required scope
billing_required	403	No active subscription on the workspace
plan_upgrade_required	403	The current plan does not include this feature
not_found	404	Resource not found
rate_limit_exceeded	429	Too many requests
internal_error	500	Server error

insufficient_credits payload

When credits are missing, the response includes an error.details object describing the credit type and the gap:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Insufficient sourcing credits to cover the returned profiles",
    "details": {
      "credit_type": "sourcing",
      "available": 0,
      "required": 1
    }
  }
}

Handling errors

TypeScript

const response = await fetch(`${BASE_URL}/contacts`, {
  headers: { Authorization: `Bearer ${apiKey}` },
});

if (!response.ok) {
  const { error } = await response.json();

  switch (error.code) {
    case "invalid_api_key":
      throw new Error("Check your API key");
    case "rate_limit_exceeded":
      // Wait and retry
      break;
    case "validation_error":
      console.error("Validation:", error.message);
      break;
    default:
      throw new Error(error.message);
  }
}

const { data } = await response.json();

Python

response = requests.get(
    f"{BASE_URL}/contacts",
    headers={"Authorization": f"Bearer {api_key}"},
)

if not response.ok:
    error = response.json()["error"]
    if error["code"] == "rate_limit_exceeded":
        time.sleep(60)  # Wait and retry
    else:
        raise Exception(f"{error['code']}: {error['message']}")

data = response.json()["data"]