Errors

Errors use standard HTTP status codes and a JSON body with a readable message.

Error body

Most errors return a detail string you can show to a person as is:

409

{"detail": "Cannot cancel a post that is published"}

A request that doesn't match the expected shape returns 422 with a list: each item gives the field path in loc and the problem in msg.

422 (invalid body)

{"detail": [
  {"loc": ["body", "targets"], "msg": "Field required", "type": "missing"}
]}

Status codes

Status	Meaning	What to do
`401`	Missing bearer token, or invalid or revoked API key.	Check the key; create a new one if it was revoked.
`402`	Payment needed: no active plan, not enough credits, declined card, or an extra account to confirm.	Choose a plan, top up or turn on automatic top-up, or confirm the extra account, in the dashboard (Plan & credits). The message says which and how many credits are needed.
`403`	Not allowed: your role, an API key on a dashboard-only endpoint (buying credits or plans, billing), or more than your plan includes.	Use an owner or admin signed in to the dashboard, or upgrade the plan.
`404`	Not found in this workspace.	Check the id, and that it belongs to the key's workspace.
`409`	The current state doesn't allow it: cancelling a published post, a top-up already processing, a plan already active.	Read the current state with a GET, then decide.
`422`	Invalid request: bad field, time in the past, account disconnected, media a platform rejects, caption too long.	Fix the request. Don't retry it unchanged.
`429`	Too many clips processing at once.	Wait for current clips to finish.
`502 / 503`	A provider (publishing, payments, dubbing) didn't answer, or a feature isn't configured on this server.	Retry later with backoff. For posts, reuse the same Idempotency-Key.

When a post fails on one platform

A post to several accounts can partly succeed. Its status is then partially_published and each target has its own status, error_message and error_category. POST /v1/posts/…/retry (or fiftyeight posts retry) retries only the targets that failed.

Retrying safely

Send an Idempotency-Key header with POST /v1/posts. Repeating the request with the same key returns the same post instead of creating a second one. A key that only produced a failed post can be reused.
POST /v1/localizations/…/publish takes an idempotency_key field for the same purpose.
Retry 5xx errors and network failures with exponential backoff. Don't retry 4xx errors unchanged.