Errors

Every error from the REST API uses one JSON shape with a stable code. Read this page when you write error handling for an automation, or when a call fails and you want to know why.

Handle an errorCopy Anchor Link

{
  "error": {
    "code": "validation_failed",
    "message": "targets.ch_7h2kq9xw3nbvd5yhzm6a.content: at most 280 characters for this channel (312)",
    "fields": { "targets.ch_7h2kq9xw3nbvd5yhzm6a.content": "at most 280 characters for this channel (312)" }
  }
}

{
  "error": { "code": "not_found", "message": "post not found" },
  "request_id": "api-1/abc-000042",
  "trace_id": "4bf92f3577b34da6a3ce929d0e0e4736"
}

Error shapeCopy Anchor Link

Error codesCopy Anchor Link

Grouped by what they are about. Every code keeps its HTTP status.

Requests and credentialsCopy Anchor Link

Posts and targetsCopy Anchor Link

A target that fails while publishing doesn't answer an error code: the post's target turns failed with the platform's message in its error (see Publishing errors).

Channels and platformsCopy Anchor Link

Accounts and sign-in (cloud)Copy Anchor Link

Plans and billingCopy Anchor Link

Common errors in detailCopy Anchor Link

402 plan_limit_exceededCopy Anchor Link

Cloud workspaces are limited by their plan. The error tells you which limit was hit:

{
  "error": {
    "code": "plan_limit_exceeded",
    "message": "The Starter plan allows 5 channels; upgrade the workspace plan to continue.",
    "details": { "limit": "channels", "max": 5, "used": 5, "plan": "starter" }
  }
}

Don't retry a 402 automatically — it won't succeed until the plan changes or the month rolls over.

401 unauthorized in the Community EditionCopy Anchor Link

"local mode needs the access token": send Authorization: Bearer {ACCESS_TOKEN}; "invalid access token": the token was rotated, print the current one with staqly serve token (Docker: docker exec staqly server token). See Authentication.

409 conflictCopy Anchor Link

A state that is already set can't be set again. Archiving an archived collection, unarchiving an active one, enabling an enabled webhook or alert (or disabling a disabled one), revoking a revoked API key or session, reporting a result a target already has, retrying a job that is not failed, cancelling a job that is not queued, and choosing the plan the workspace is already on all answer 409 and change nothing: no new version, no event, no webhook. A PATCH that changes other fields as well is accepted; the unchanged state field is then ignored.

422 on posts and targetsCopy Anchor Link

GET /v1/posts/{id}/preview reports the same problems as warnings per target without failing.

Publishing errorsCopy Anchor Link

Publishing happens later, in a job, so its failures don't come back as an HTTP error: the target turns failed, its error says why, post.target_failed is emitted (and post.failed once every target settled with at least one failed) and an alert can tell you. Staqly sorts platform answers into three kinds:

Messages staqly itself writes on a failed target:

Each platform's page lists what it refuses, e.g. X.

Next stepsCopy Anchor Link