Guides

Errors & retries

Every error — at the request level or per target — uses one normalised shape, so you (or an agent) can handle failures the same way everywhere.

The error envelope

Errors return { "error": { … } } with a stable type, a human message, an optional platform, and a retryable boolean.

{
  "error": {
    "type": "entitlement_exceeded",
    "message": "Not enough credits: this post costs 5, you have 2.",
    "platform": null,
    "retryable": false
  }
}

Two levels of error

Request-level — the whole call is rejected (bad auth, malformed body, out of credits). Returned with a 4xx status and the envelope above.
Per-target — the call succeeds but one platform fails (over a limit, invalid option). The post is partial, and the failing targets[].error carries the same envelope. You're not charged for failed targets.

Error types

Type	HTTP	Meaning	Retry?
`invalid_request`	400	Malformed body or invalid field/option.	Fix & resend
`unauthorized`	401	Missing or invalid API key.	No
`entitlement_exceeded`	402	Out of credits, or your plan doesn't allow this (e.g. X/TikTok on free).	After topping up / upgrading
`rate_limited`	429	Too many requests.	Yes, after a short back-off
platform errors	—	A specific network rejected the target (see `platform`).	Depends on the message

Retrying safely

When retryable is true (e.g. rate_limited), back off and retry. Always send the same Idempotency-Key on retries so a post that actually went out isn't duplicated. On 429, honour any Retry-After header. Non-retryable errors (unauthorized, invalid_request) need a fix, not a retry.