Errors

Every error has the same shape:

{ "error": { "code": "not_found", "message": "No such Post in this Workspace." } }

code is for your code and never changes. message is for people, and may be reworded.

Blockers

When a Post would not publish as it stands, nothing is made and the 422 lists every reason at once, as blockers:

{
  "error": {
    "code": "blocked",
    "message": "This Post can’t be published as it stands.",
    "blockers": [
      { "code": "incomplete", "message": "Instagram needs an image or video." },
      { "code": "problem", "message": "@nordlysbakery is over its limit — 512 of 500." }
    ]
  }
}

A blocker’s code is incomplete when something is missing and problem when something is wrong. Fix them all and send it again.

Plan limits

A Post that would pass the Workspace’s plan — how many Posts it may have queued or publish a month, or its storage — is refused with plan_limit. When a plan that raises the limit can be bought, upgrade names it:

{
  "error": {
    "code": "plan_limit",
    "message": "That would pass the Workspace’s plan limit.",
    "blockers": [{ "code": "problem", "message": "…" }],
    "upgrade": { "plan": "pro", "limit": "storage", "label": "Pro holds 20 GB" }
  }
}

limit is slots, seats, volume or storage. Show label beside a link to the plans, or leave it to a person: the API never changes a plan.

A Post to X needs Post credits, a pack of 30 posts a month shared by every X Channel in the Workspace. Without one left for the billing period the Post is due in, it is refused with plan_limit and a blocker saying so, and no upgrade: credits are bought in the app, on any plan. Trying a failed X Variant again needs a credit too.

Codes

Status	Code	Means
400	invalid_request	The body or query does not fit the schema; message says where
400	invalid_json	The body is not JSON
400	invalid_cursor	That cursor did not come from us
401	unauthorized	No credential, or one that is unknown or revoked
403	insufficient_scope	The credential lacks the permission
404	not_found	No such endpoint, or no such thing in this Workspace
405	method_not_allowed	The endpoint does not take that method
409	channel_disconnected	The Variant’s Channel is disconnected; connecting it again lets it be tried again
422	blocked	The Post would not publish; see blockers
422	plan_limit	It would pass the plan; see upgrade
422	media_unavailable	A file is not this Workspace’s, not uploaded, or already in a Post
422	upload_refused	An upload Pubrivo does not take — its type, size, or the storage left
422	upload_incomplete	The file did not arrive whole; it was removed
422	not_failed	Only a failed Variant can be tried again
429	rate_limited	See rate limits
500	internal	Ours. Try again
503	media_not_configured	Media cannot be taken right now

A Variant that fails after it was accepted is not an error response: it is a failed status on the Variant, with a failureReason. See the data model.