Errors

All errors use this shape:

{
  "error": {
    "code": "insufficient_credits",
    "message": "Not enough credits to add this lead.",
    "details": {}
  }
}

Branch on error.code, not only HTTP status.

HTTP status

StatusWhen
200Success
400Validation
401Missing / invalid key
403Plan required, insufficient credits, Sales Nav required, account disconnected
404Unknown campaign / lead
409Idempotency conflict
413Request body over 128 KiB
429Rate limit or LinkedIn daily quota
502 / 503Temporary upstream failure

A 400 also covers a malformed id in the path (for example a campaignId we cannot address); error.details.fields names the segment.

On the 10 idempotent POST routes (add lead, leads batch, batch-update, batch-delete, create campaign, lookalike, create tag, create template, assign template, send message), a 503 may mean we could not record your Idempotency-Key. In that case nothing was performed — the message states so — and retrying the same key is safe.

Success bodies are top-level JSON (no { "data": ... } wrapper).

Error codes

CodeMeaning
unauthorizedBad or missing API key
plan_requiredPlan not eligible for API
validation_errorBad body/query (unknown fields, bad URL, bad cursor)
not_foundUnknown resource
conflictIdempotency conflict
insufficient_creditsNeed credits to insert lead
insufficient_lookalike_creditsNeed Lookalike allowance to create/extend (403)
lookalike_exhaustedNo more Lookalike results for this profile/titles/locations on this campaign (400)
alternate_seed_requires_new_campaignExtend used a different LinkedIn profile than the campaign seed — create a new Lookalike campaign (400)
lookalike_provider_mismatchRare: Lookalike extend cannot continue on this campaign — create a new Lookalike campaign (400)
account_disconnectedLinkedIn account not connected / inactive (incl. bad selectedAccounts on create/update template, and assign-template when template accounts are not working)
sales_nav_requiredSales Nav search without a stored Sales Navigator contract (Premium is not enough), or the live session cannot search Sales Navigator (reconnect, then wait; do not retry immediately)
rate_limitedRPM / burst limit
linkedin_daily_quotaDaily LinkedIn quota
send_failedMessage send failed
upstream_unavailableTemporary failure