{
"success": false,
"error": {
"code": "CHANNEL_ERROR",
"message": "No Sales Nav license found for this account",
"sub_code": "NO_SALES_NAV_SEAT"
},
"metadata": {
"action": "search_people_nav",
"credits_consumed": 1,
"timestamp": "2026-10-15T12:00:00Z"
}
}
code and sub_code, never on message: the text may change, the codes don’t. sub_code is always present on CHANNEL_ERROR, and on other codes only in the cases listed under Sub-codes. When it is absent, handle the error on code alone; treat an unknown sub_code the same way.
Handling errors
| Case | What to do | When |
|---|---|---|
| LinkedIn limited the account | Pause this action on the account. When LinkedIn lifts the limit depends on the case. | LINKEDIN_RATE_LIMITED, SALES_NAV_RATE_LIMITED, FUSE_LIMIT_EXCEEDED, QUOTA_EXCEEDED, INMAIL_MONTHLY_FUSE_LIMIT |
| The account is disconnected | Reconnect it with POST /v2/login. | ACCOUNT_INACTIVE (except NOT_CONNECTED), ACCOUNT_DISCONNECTED, the seat sub-codes |
| The target can’t be reached | Skip it and move on. | PROFILE_NOT_FOUND, CANT_RESEND_YET, RECIPIENT_NOT_FIRST_DEGREE_CONNECTION, other CHANNEL_ERROR refusals |
| The request is wrong | Fix it, or top up on INSUFFICIENT_CREDITS. | Other INVALID_PARAMS, INVALID_ACTION, INVALID_ACCOUNT, INSUFFICIENT_CREDITS |
| Temporary failure on our side | The request was fine. On CONCURRENCY_LIMIT, send fewer requests in parallel. | INTERNAL_ERROR, UPSTREAM_ERROR, *_UNAVAILABLE, CONCURRENCY_LIMIT, NOT_CONNECTED |
NOT_CONNECTED means the connection to WhatsApp dropped and is being reopened automatically. Retry later and do not re-link the number. No webhook is sent when the connection drops or comes back; re-link only when you receive a disconnection event.
Codes
| Code | HTTP | Meaning |
|---|---|---|
INVALID_API_KEY | 403 | The x-api-key header is missing or invalid. |
INVALID_ACCOUNT | 404 | The account_id doesn’t exist under your API key. |
ACCOUNT_INACTIVE | 403 | The account’s session stopped working during the call. |
INVALID_ACTION | 400 | The action doesn’t exist for this endpoint, or not on this account (no credit charged). |
INVALID_PARAMS | 400 | A parameter is missing or invalid, the target doesn’t exist (PROFILE_NOT_FOUND), or the account_id is disconnected (ACCOUNT_DISCONNECTED). |
RATE_LIMITED | 429 | Too many concurrent requests on your key, or LinkedIn limited the account. |
INSUFFICIENT_CREDITS | 402 | Not enough credits. Only on credit plans, and for email enrichment on every plan. |
SEAT_LIMIT_REACHED | 402 | Per-account plan: all seats are used and auto-upgrade is off. Add seats or turn auto-upgrade on in Billing. |
CHANNEL_ERROR | 422 | The request was valid but the platform refused it. sub_code says why. |
INTERNAL_ERROR | 500 | Unexpected error on our side. Contact support@linkupapi.com if it persists. |
Examples
{
"success": false,
"error": {
"code": "INVALID_API_KEY",
"message": "Invalid API Key"
},
"metadata": { "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "INVALID_ACCOUNT",
"message": "Account not found"
},
"metadata": { "action": "get", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "ACCOUNT_INACTIVE",
"message": "LinkedIn account is no longer connected. Please re-authenticate.",
"sub_code": "LINKEDIN_SESSION_EXPIRED"
},
"metadata": { "action": "get", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "INVALID_ACTION",
"message": "Unsupported action 'foo_bar' for category 'profiles' on platform 'linkedin'"
},
"metadata": { "action": "foo_bar", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "INVALID_PARAMS",
"message": "Profile not found",
"sub_code": "PROFILE_NOT_FOUND"
},
"metadata": { "action": "get", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "RATE_LIMITED",
"message": "LinkedIn invitation limit reached on this account (FUSE_LIMIT_EXCEEDED)",
"sub_code": "FUSE_LIMIT_EXCEEDED"
},
"metadata": { "action": "invite", "credits_consumed": 1, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "INSUFFICIENT_CREDITS",
"message": "Not enough credits"
},
"metadata": { "action": "get", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "SEAT_LIMIT_REACHED",
"message": "Seat limit reached: 3/3 accounts connected. Add seats or turn on auto-upgrade in your dashboard to connect more accounts."
},
"metadata": { "action": "login", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "CHANNEL_ERROR",
"message": "LinkedIn won't accept this invitation yet: after withdrawing an invitation, the same member can only be invited again about 3 weeks later (CANT_RESEND_YET)",
"sub_code": "CANT_RESEND_YET"
},
"metadata": { "action": "invite", "credits_consumed": 1, "timestamp": "2026-10-15T12:00:00Z" }
}
{
"success": false,
"error": {
"code": "INTERNAL_ERROR",
"message": "An unexpected error occurred while processing your request"
},
"metadata": { "action": "get", "credits_consumed": 0, "timestamp": "2026-10-15T12:00:00Z" }
}
Sub-codes
| Area | sub_code |
|---|---|
| Temporary (our side) | UPSTREAM_ERROR, WHATSAPP_UNAVAILABLE, SALES_NAV_SEAT_UNAVAILABLE, NO_PROXY_AVAILABLE, MONITOR_START_FAILED, MAILBOX_PROVIDER_ERROR, NOT_CONNECTED (WhatsApp reconnecting, sent with ACCOUNT_INACTIVE) |
Rate limits (RATE_LIMITED) | CONCURRENCY_LIMIT (your key), LINKEDIN_RATE_LIMITED, SALES_NAV_RATE_LIMITED, FUSE_LIMIT_EXCEEDED, QUOTA_EXCEEDED (invitations), INMAIL_MONTHLY_FUSE_LIMIT (Sales Nav InMails) |
Disconnected (ACCOUNT_INACTIVE) | LINKEDIN_SESSION_EXPIRED, MAILBOX_AUTH_REVOKED, MAILBOX_AUTH_FAILED, RECRUITER_SEAT_EXPIRED |
Request (INVALID_PARAMS) | PROFILE_NOT_FOUND, ACCOUNT_DISCONNECTED, BAD_CREDENTIALS (login), and on a refused send LinkedIn’s own code: RECIPIENT_NOT_FIRST_DEGREE_CONNECTION, NOT_ALLOWED_PREMIUM_INMAIL_SUBSEQUENT_REPLY… |
| Invitations | CANT_RESEND_YET (already connected, invitation pending, or recently withdrawn), ALREADY_CONNECTED, ALREADY_INVITED, CUSTOM_MESSAGE_TOO_LONG, INVITATION_REFUSED, INVITATION_NOT_CONFIRMED (check with check_invitation), INVITATION_NOT_PENDING |
| LinkedIn refusals | PROFILE_RESTRICTED, ENTITY_NOT_FOUND, GEO_RESTRICTED, INMAIL_NOT_ALLOWED, JOB_POSTING_FAILED, LINKEDIN_REFUSED |
| Sales Navigator | NO_SALES_NAV_SEAT, SALES_NAV_SEAT_INVALID, SALES_NAV_ACCESS_DENIED, SALES_NAV_BAD_REQUEST, SALES_NAV_NOT_FOUND, ACCOUNT_UNDER_REVIEW, MISSING_CONVERSATION_ID, SALES_NAV_ERROR |
| Recruiter | RECRUITER_SEAT_MISSING, RECRUITER_SEAT_EXPIRED, NO_RECRUITER_LICENSE, RECRUITER_LOGIN_FAILED, RECRUITER_ERROR |
| Login & checkpoint | LOGIN_FAILED, ACCOUNT_RESTRICTED, ACCOUNT_VERIFICATION_REQUIRED (LinkedIn asks the member to verify the account on linkedin.com, e.g. add a phone number; retry the login after), INVALID_LOGIN_TOKEN, CHECKPOINT_VERIFICATION_FAILED, CHECKPOINT_SESSION_EXPIRED, CHECKPOINT_RESEND_FAILED |
| Accounts | SESSION_REJECTED_THROUGH_PROXY (proxy or country change refused, nothing changed) |
MAILBOX_AUTHORIZATION_FAILED, MAILBOX_PERMISSIONS_MISSING, MAILBOX_CONNECTION_FAILED, NO_GMAIL_MAILBOX, MICROSOFT_SENDING_UNAVAILABLE, IMAP_AUTH_FAILED, IMAP_CONNECTION_FAILED | |
WHATSAPP_LINK_EXPIRED, WHATSAPP_LINK_REFUSED, NOT_ON_WHATSAPP, SEND_FAILED, CHAT_NOT_FOUND | |
| iMessage | IMESSAGE_CONTACT_LIMIT, IMESSAGE_DAILY_NEW_CONTACT_LIMIT, IMESSAGE_NEW_CONTACT_INTERVAL, IMESSAGE_FOLLOW_UP_INTERVAL, IMESSAGE_FOLLOW_UP_TOO_SOON, IMESSAGE_RECIPIENT_MUST_REPLY, IMESSAGE_FIRST_MESSAGE_CONTENT, IMESSAGE_SEND_REFUSED, IMESSAGE_TYPING_UNAVAILABLE, IMESSAGE_UNAVAILABLE — see iMessage limits |
| Other | COMPANY_NOT_FOUND (enrich), CONNECT_LINK_UNAVAILABLE, CONNECTION_FAILED (hosted connection links) |