Errors
One error body everywhere, the codes, and what to retry.
Every error has the same body:
{
"status": 429,
"type": "errors/too_many_requests",
"code": "safety-floor",
"title": "Daily safety limit reached for invite.",
"detail": "Daily safety limit reached for invite.",
"retry_after_ms": 43200000
}statusandtypeare the contract: branch on them.codeis Swarmhit's finer reason, stable, for logs and support.titleanddetailare one sentence a person can read, safe to show.- Some errors add a field:
retry_after_ms(on a 429: wait at least this long),replied_at(recipient-replied),ends_at(whatsapp-new-chats-blocked).
Retry rule of thumb: retry 429 (after retry_after_ms), 502 and 503; never retry
400, 401, 403, 404, 409 or 422 unchanged.
The errors
| HTTP | type | code | When |
|---|---|---|---|
| 400 | errors/invalid_parameters | bad-request | A body or query fails its schema, a required field is missing, the JSON does not parse. |
| 401 | errors/unauthorized | unauthorized | Missing, wrong, revoked or expired API key. |
| 401 | errors/invalid_credentials | bad-credentials | LinkedIn refused the email and password (or the TOTP secret), or a mailbox refused its login on a connect. |
| 401 | errors/invalid_checkpoint_solution | code-rejected | LinkedIn did not accept the code. The sign-in still waits: send the right code, or ask for a new one. |
| 401 | errors/disconnected_account | no-session, session-expired | The account has no working session (never signed in, LinkedIn signed it out, a WhatsApp number no longer linked). Reconnect it. |
| 402 | errors/payment_required | payment-method-required, payment-failed | No valid card on file for live keys, or the charge for a new account was declined (see Authentication). |
| 403 | errors/forbidden | forbidden | The key was not made for this channel. |
| 403 | errors/account_restricted | restricted | LinkedIn restricted the account. A person must look before any retry. |
| 403 | errors/account_restricted | whatsapp-new-chats-blocked | WhatsApp blocks this number from starting chats until ends_at; existing chats still work. |
| 403 | errors/client_suspended | client-suspended | Your company's access is suspended. |
| 403 | errors/insufficient_permissions | whatsapp-refused | WhatsApp refused the action (not a group admin, not your message). |
| 404 | errors/resource_not_found | not-found, account-not-found, profile-not-found | No such route, account, chat, message, invitation or profile (or not yours). |
| 408 | errors/request_timeout | sign-in-timeout, connect-timeout | The sign-in, or LinkedIn's answer to a cookie connect, took too long. Try again. |
| 408 | errors/checkpoint_expired | no-attempt | No sign-in is waiting for a code or a live view any more. Start the connect again. |
| 409 | errors/sign_in_in_progress | sign-in-in-progress | Another sign-in for this account is running. |
| 409 | errors/account_paused | paused | The account is paused. Resume it first. |
| 409 | errors/identity_mismatch | identity-mismatch | The session belongs to another LinkedIn member than this account's. |
| 409 | errors/recipient_replied | recipient-replied | unless_replied_since was set and the recipient wrote after it: nothing was sent. replied_at says when. |
| 413 | errors/content_too_large | bad-request | The body is over the size limit. |
| 422 | errors/not_supported | not-supported | Swarmhit does not offer this (a passthrough write, a hosted connection link, a feature switched off, some Sales Navigator InMail actions). |
| 422 | errors/unsupported | not-supported | A Sales Navigator search URL or filter Swarmhit cannot run. |
| 422 | errors/no_browser | not-supported | The action needs a browser and this account (connected by cookie) has none. |
| 422 | errors/feature_not_subscribed | sales-seat-required | The member has no Premium or Sales Navigator seat (InMail). |
| 422 | errors/insufficient_credits | linkedin-error | No InMail credits left. |
| 422 | errors/cannot_resend_yet | invite-limit, already-invited | LinkedIn's invitation limit is reached, or it will not let you invite this person again yet. Cool the account down; do not retry. |
| 422 | errors/already_invited_recently | already-invited | An invitation to this person is already pending. Treat it as sent. |
| 422 | errors/too_many_characters | bad-request | An invitation note over 300 characters (or over LinkedIn's limit for this member). |
| 422 | errors/invalid_recipient | invalid-recipient, not-on-whatsapp, not-supported | This person cannot be messaged from this account, or the number is not on WhatsApp. |
| 422 | errors/limit_exceeded | whatsapp-quota-reached | WhatsApp's new-chat quota for this number is spent for its cycle. |
| 422 | errors/proxy_error | no-ip-in-country | No IP is available in the account's country. Pick a nearby country. |
| 429 | errors/too_many_requests | rate-limited | LinkedIn is limiting the account (its 429 or 999): nothing reaches LinkedIn until retry_after_ms has passed. |
| 429 | errors/too_many_requests | safety-floor | A daily safety cap is reached (see Write safety). |
| 429 | errors/too_many_requests | account-busy | Another write, a sign-in, the minimum gap between writes, or a send with the same client_id in progress. |
| 429 | errors/too_many_requests | sign-in-throttled | Too many sign-ins for this account lately. |
| 500 | errors/unexpected_error | internal | A bug on our side, reported automatically. |
| 502 | errors/unexpected_error | linkedin-error, linkedin-endpoint-changed, sign-in-failed | LinkedIn could not be reached or answered oddly, or the sign-in broke. Retry later. |
| 502 | errors/attachment_upload_failed | linkedin-error | An attachment could not be uploaded to LinkedIn; nothing was sent. |
| 502 | errors/provider_unavailable | browser-error | The account's browser could not start. |
| 502 | errors/provider_error | whatsapp-error | WhatsApp failed the call. Retry later. |
| 503 | errors/proxy_error | proxy-drift, proxy-down | The account's exit IP left its country or does not answer. The account is held until it is back; do not reconnect it for this. |
| 503 | errors/no_client_session | whatsapp-connecting | The number is between two connections. Retry in a moment. |
| 503 | errors/provider_unavailable | proxy-provider-unavailable | A service Swarmhit depends on is down or asked us to slow down. |
| 503 | errors/service_unavailable | browser-busy, linkedin-error | Every sign-in browser is busy, the Sales Navigator session is being renewed, or an upload took too long. Retry shortly. |
| LinkedIn's | errors/unexpected_error | linkedin-error | LinkedIn answered an error Swarmhit has no better row for: passed through with LinkedIn's own status. |
| HTTP | type | When |
|---|---|---|
| 400 | errors/invalid_headers | A custom_headers entry that is not allowed, or a line break in one. |
| 401 | errors/disconnected_account | The mailbox refused Swarmhit's login: reconnect it. |
| 422 | errors/cant_send_message | The mail server refused the message. |
| 422 | errors/send_as_denied | from is not the mailbox's own address. |
| 422 | errors/parent_mail_not_found | reply_to names no mail of this mailbox. |
| 422 | errors/not_supported_by_provider | The mailbox does not support this (for example the address book). |
| 429 | errors/too_many_requests | Connects and login checks are over 120 per 10 minutes, or the mail provider asked to slow down. |
| 502 | errors/provider_error | The mail service failed the call. Retry later. |
| 503 | errors/provider_unavailable | The mail service is unavailable for a moment. Retry shortly. |
The API reference lists, on each endpoint, the errors it can answer.
Every 429 is answered before anything reaches LinkedIn or WhatsApp, so retrying it
can never send twice.