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, Sales Nav required, account disconnected |
| 404 | Unknown campaign / lead |
| 409 | Idempotency conflict |
| 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 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
| Code | Meaning |
|---|---|
unauthorized | Bad or missing API key |
plan_required | Plan not eligible for API |
validation_error | Bad body/query (unknown fields, bad URL, bad cursor) |
not_found | Unknown resource |
conflict | Idempotency conflict |
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) |
alternate_seed_requires_new_campaign | Extend used a different LinkedIn profile than the campaign seed — create a new Lookalike campaign (400) |
lookalike_provider_mismatch | Rare: Lookalike extend cannot continue on this campaign — create a new Lookalike campaign (400) |
account_disconnected | LinkedIn account not connected / inactive (incl. bad selectedAccounts on create/update template, and assign-template when template accounts are not working) |
sales_nav_required | Sales 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_limited | RPM / burst limit |
linkedin_daily_quota | Daily LinkedIn quota |
send_failed | Message send failed |
upstream_unavailable | Temporary failure |