Fundamentals

Errors

Every failure returns the same shape and a status code that tells you whether retrying makes sense.

The shape

any error

{
  "error": "At least one platform is required"
}

Messages are written to be shown to a person or read by an agent — they say what went wrong and, where possible, what to do instead. They are not stable identifiers; do not branch on their exact text.

Status codes

Code	Means	Retry?
`400`	The request is malformed or a value is invalid	Only after fixing it
`401`	Token missing, unrecognised or revoked	No — check the key
`403`	The token lacks the scope this call needs	No — issue a token with the scope
`404`	The object does not exist in this workspace	No
`429`	Rate limit or monthly quota	Rate limit yes, quota no
`500`	Something failed on our side	Yes, with backoff

The ones you will actually see

Message	What happened
Invalid or missing API token…	The header is absent, malformed, or the token was revoked. 401.
This API token is missing the “`publish`” scope…	The call is valid but the token was not granted that scope. 403.
Not connected in this workspace: tiktok	You targeted a platform with no active account here. Call /accounts first. 400.
Scheduled time is in the past — pick a future time.	scheduledAt must be ahead of now. 400.
Use either publishNow or scheduledAt, not both.	They are mutually exclusive. 400.
Unknown comment for this workspace…	The comment id is not one this workspace received. 400.
Monthly … quota reached (1000/1000)	A monthly pool is spent. 429, and retrying will not help.

404 is deliberate for foreign objects

Asking for a post or a comment belonging to another workspace returns 404, not 403 — the object genuinely does not exist as far as your token is concerned. That also means the API cannot be used to test whether an id exists elsewhere.

Partial success on publish

Publishing to several platforms is not all-or-nothing. If one platform rejects the post, the request still succeeds and the per-platform outcome is in the response — check results, not just the status code.

partial publish

{
  "post": { "id": "cmq7…", "status": "partial" },
  "results": [
    { "platform": "instagram", "success": true,  "url": "https://…" },
    { "platform": "x",         "success": false, "error": "Monthly X posts & replies quota reached (300/300)." }
  ],
  "note": "Published on some platforms — check results for failures."
}

published — every platform accepted it.
partial — at least one succeeded and at least one failed.
failed — none succeeded.

Errors as an agent sees them

Over MCP, the same failures come back as tool results marked isError rather than as protocol errors, so the model reads the message and adapts instead of the call blowing up. Unexpected internal failures return a generic message — details are logged on our side rather than sent to the client.

Was this page helpful?