Errors

What each status code means, the codes a workflow can branch on, and what to change before you try again.

قراءة 3 دقائق All plans

Errors from these endpoints come back as JSON, never as an HTML error page, so your code can read the reason rather than guess it from the status code alone. Read the message and show it — the wording is written to tell somebody what to do next.

STATUSWHAT HAPPENEDWHAT TO DO

401 No bearer token was sent, or the key sent is wrong or has been revoked. Check the Authorization header, then check the key is still active under Settings → API Keys.

404 The article does not exist, or it belongs to a different website. Take article ids from a list made with the same key.

409 Connect was refused because the website already publishes its articles somewhere else. Disconnect the destination named in the message, in the console, then connect again.

422 A required value was missing, or a value was outside the range the endpoint allows. Read the errors object, fix the fields it names and send the request again.

429 You have called more often than the ceiling allows — 120 requests a minute, or 2,000 an hour. Wait the number of seconds in the Retry-After header, then try again. If you hit this regularly, cache the answers rather than asking again.

The two 401 messages

They are worth telling apart, because they need different fixes.

Missing API key. Send it as an "Authorization: Bearer" header. — nothing arrived. Your header is absent or misspelled.
Invalid or revoked API key. — something arrived and it is not a working key. Either it was mistyped, or somebody revoked it. Revoking takes effect on the very next request, so a key that worked a minute ago can return this.

Requests that never get that far

A request missing a required value, or carrying one outside the range the endpoint allows, is refused before anything is read or changed. Nothing is half-done — fix the value and send it again.

These come back as 422, and that body has a different shape from the others: a message, plus an errors object keyed by field name, and no success flag at all. Write your parser to expect both shapes.

The commonest cases are a month or year left off keywords, a per_page above 100 on articles, and a site_url that is not a full address on connect.

Codes your workflow can branch on

Endpoints outside /platform also carry a machine-readable code, so an automation can decide what to do without reading English. The sentence is still there for a human to see.

SHAPE

{
  "success": false,
  "error": {
    "code": "plan_limit_reached",
    "message": "This website has no social posts left this period.",
    "details": {
      "metric": "social_posts",
      "limit": 30,
      "used": 30,
      "resets_at": "2026-10-01T00:00:00+00:00"
    }
  },
  "message": "This website has no social posts left this period."
}

CODEWHAT HAPPENEDWHAT TO DO

plan_limit_reached No allowance left this period. 402, and nothing was saved. Wait for resets_at, or upgrade. Do not retry.

feature_not_available This plan does not include what you asked for. 402 Upgrade, or stop asking for it.

website_id_required Your key reaches several websites and you named none. 422 Send website_id — see List your websites.

not_a_member That website is not available to this key. 403 Check the id. Being removed from a website revokes your key's reach into it.

insufficient_scope The key was not given this permission. 403 Make a new key with it.

insufficient_role You do not have the standing on that website. 403 Ask an admin, or have them make the key.

media_required Named channels cannot publish text alone. 422 Send an image_prompt, or drop those channels.

slot_in_the_past The date has already passed. 422 Send a future date.

ping_failed A webhook URL did not answer the test. 422 Fix the URL. Nothing was saved.

معلومة مفيدة A 402 is never worth retrying — the answer will be the same until the period rolls over or the plan changes. A 429 always is, after Retry-After.

Calling too often

Each key may make 120 requests a minute and 2,000 an hour. The count is against the key, not your server, so several sites sharing one office connection each get their own allowance — and one site stuck in a retry loop cannot spend another’s.

Every response carries X-RateLimit-Limit and X-RateLimit-Remaining so you can see how much is left before you run out. Go over and you get 429 with a Retry-After header saying how many seconds to wait.

معلومة مفيدة The ceiling is a backstop against a loop, not a budget to plan around. Normal use — a plugin syncing on a schedule, a site fetching articles as it publishes them — never comes close. If you are hitting it, something is asking the same question repeatedly; cache the answer instead.

هل أجابت هذه الصفحة عن سؤالك؟ نعم ليس تمامًا

Disconnect a site