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

Status	When
200	Success
400	Validation
401	Missing / invalid key
403	Plan required, insufficient credits (normal or Lookalike), Sales Nav required, account disconnected
404	Unknown campaign / lead
409	Idempotency conflict, wrong campaign state for start/pause, or batch-delete while the campaign is still finding/importing leads
413	Request body over 128 KiB
429	Rate limit or LinkedIn daily quota
502 / 503	Temporary 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 POST .../leads, POST .../leads/batch, POST .../leads/batch-update, POST .../leads/batch-delete, POST /inbox/messages, and POST /campaigns/lookalike, 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

Code	Meaning
`unauthorized`	Bad or missing API key
`plan_required`	Plan not eligible for API (or Lookalike blocked for workspace)
`validation_error`	Bad body/query (unknown fields, bad URL, bad cursor)
`not_found`	Unknown resource
`conflict`	Idempotency conflict, wrong campaign state (start/pause / batch-delete during lead import), or similar
`insufficient_credits`	Need credits to insert lead
`insufficient_lookalike_credits`	Need Lookalike allowance to create/extend (403)
`lookalike_exhausted`	No more Lookalike results for this profile/titles/locations on this campaign (400)
`account_disconnected`	LinkedIn account not usable
`sales_nav_required`	Sales Nav search without SN, or SN session not usable (reconnect the LinkedIn account)
`rate_limited`	RPM / burst limit
`linkedin_daily_quota`	Daily LinkedIn quota
`send_failed`	Message send failed
`upstream_unavailable`	Temporary failure