Reference
Errors
Every code the API can return, generated from the spec, with what it means and what to do about it.
#The shape
Errors are JSON, always with a code and a message:
{
"error": "invalid_connection",
"message": "Connection 'linkedn' not found. Available connections: linkedin, x"
}platform_rejected and internal_server_error also carry a req_id. The 429 body is the exception: it is { "error": "too many requests" } and has no message.
results item or a posts item, the same vocabulary shows up as { "code": ..., "message": ... }. A fan-out to several connections reports a per-connection failure that way, inside a 200, rather than failing the request.#Every code
None of the slugs you sent match a connection of yours. On the fan-out endpoint this only fires when none of them match: one bad slug among good ones is a failed item inside a 200.
what to doCall GET /connections and post to a slug from that list. The message names the ones you do have.
- Connection 'linkedn' not found. Available connections: linkedin, x
- None of the given connections were found: linkedn, twiter
POST /post/{connectionSlug} · POST /posts
The request itself is wrong: a malformed body, bad query parameters, a scheduled time in the past or more than 30 days out, or a post that cannot be cancelled any more.
what to doRead the message, fix the request, then retry. Retrying the same request unchanged gives the same answer.
- Scheduled time must be in the future.
- Request body must be JSON with a non-empty text and a non-empty connectionSlugs array.
- Invalid query parameters. status must be one of sent, scheduled, processing, failed, cancelled. limit must be between 1 and 100. offset must be 0 or greater.
- postId must be a valid post id.
- Only scheduled posts that have not been sent yet can be cancelled.
- url must be an https URL.
- webhookId must be a valid webhook id.
- Invalid query parameters. limit must be between 1 and 100.
POST /post/{connectionSlug} · POST /posts · GET /posts · GET /posts/{postId} · DELETE /posts/{postId} · POST /webhooks · DELETE /webhooks/{webhookId} · GET /webhooks/{webhookId}/deliveries
Posting to X bills a flat fee per post and your account has no payment method. LinkedIn is unaffected.
what to doAdd a payment method in Settings. Subscribing at two accounts is still $0 a month, so adding a card does not push you onto a paid tier.
- X charges per post. Add a card and pay a flat 2 cents per post, 25 cents with a link, nothing else.
POST /post/{connectionSlug}
Your own monthly X spend cap is reached.
what to doRaise the cap in Settings, or wait for the month to roll over. Posts to other platforms keep going out.
- Your monthly X spend cap is reached. Raise it in Settings.
POST /post/{connectionSlug}
A monthly cap is used up: messages on any plan, or posts on a legacy plan. Posts on the plans sold today are unlimited, so this never fires for them.
what to doUpgrade the plan or wait for the month to reset. The message says which limit you hit.
- You have reached your monthly post limit (3). Upgrade your plan for more posts.
POST /post/{connectionSlug}
No post or webhook of yours with that id. Something belonging to someone else is a 404 too, same as something that never existed.
what to doCheck the id. Post ids come from POST /posts or GET /posts, webhook ids from POST /webhooks or GET /webhooks.
- Post not found.
- Webhook not found.
GET /posts/{postId} · DELETE /posts/{postId} · DELETE /webhooks/{webhookId} · GET /webhooks/{webhookId}/deliveries
This Idempotency-Key was already used with a different body, or its first request is still running.
what to doUse a fresh key for a different post. If the first request is still in flight, wait and retry the same key: you will get the stored response back.
- This Idempotency-Key was already used with a different request body.
- A request with this Idempotency-Key is already in progress.
POST /posts
The worker claimed the post while your cancel was in flight. The post was not cancelled and is on its way out.
what to doRead it back with GET /posts/{postId} to see how it ended. There is nothing to retry.
- The post was picked up for sending and can no longer be cancelled.
DELETE /posts/{postId}
POST /post/{connectionSlug} got a Content-Type other than text/plain or application/x-www-form-urlencoded.
what to doSend text/plain, or leave the header off. If you want to send JSON, use POST /posts instead.
- Unsupported Content-Type. Use text/plain or omit the header.
POST /post/{connectionSlug}
The platform refused the post: a duplicate, a policy violation, or something else on their side.
what to doChange the text and post again. This body carries a req_id: quote it if the rejection looks wrong.
- LinkedIn: duplicate post was detected
POST /post/{connectionSlug}
More than 60 requests in a minute for this API key and endpoint group. This is the one error body with no message field.
what to doSleep until x-ratelimit-reset and retry. On POST /posts, reuse the same Idempotency-Key so the retry cannot double-post.
GET /connections · POST /post/{connectionSlug} · POST /posts · GET /posts · GET /posts/{postId} · DELETE /posts/{postId} · POST /webhooks · GET /webhooks · DELETE /webhooks/{webhookId} · GET /webhooks/{webhookId}/deliveries
Our fault.
what to doRetry with backoff. If it keeps happening, quote the req_id from the body or the x-request-id header.
- An unexpected error occurred
GET /connections · POST /post/{connectionSlug} · POST /posts · GET /posts · GET /posts/{postId} · DELETE /posts/{postId} · POST /webhooks · GET /webhooks · DELETE /webhooks/{webhookId} · GET /webhooks/{webhookId}/deliveries
#The 402 pair
Both 402s are about X, which bills a flat fee per post: 2 cents, or 25 cents with a link. payment_method_required means there is no card on the account; spend_cap_reached means you hit a cap you set yourself. Posts to LinkedIn are free and are never blocked by either.
The detail is on plans and X fees.
#What is safe to retry
429and500: retry with backoff.402and403: retrying changes nothing until you add a payment method, raise the cap, or upgrade.400,401,404,415and422: fix the request first.- On
POST /posts, any retry should carry the same Idempotency-Key.