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, because nothing could proceed for any destination. An unknown media id, an unknown account id, no text, bad auth, out of credits. Returned with a 4xx status and the envelope above. No post is created.
• Per-target: the request was fine, but a network will not take it (over a limit, missing media, invalid option). The call returns 201, the post is created, and the failing targets[].error carries the same envelope. You're not charged for failed targets.

A per-target failure never changes the status code. You get 201 whether one target failed or all of them, and whether the post was immediate or scheduled. So read state and targets[], not just the status:

When a network refuses

These come from the network rather than from us. We recognise the message, attach a code you can branch on, and say what actually fixes it. Anything we do not recognise is passed through unchanged, because a confident wrong instruction is worse than none.

Checking before you publish costs nothing: POST /v1/posts/validate runs the same checks and returns the same codes and fixes per target, without creating anything.

Error types

Error codes

Alongside type, a validation error carries a granular code, the request field at fault in param, a plain-language fix, and a docs link back to this table. Branch on code: it is stable, and it is the only field specific enough to act on. type stays coarse on purpose.

{
  "type": "invalid_input",
  "message": "TikTok requires at least one media item",
  "code": "media_required",
  "fix": "TikTok cannot publish text on its own. Attach an image or a video and post again.",
  "docs": "https://docs.postlake.dev/errors#media_required",
  "param": "media",
  "platform": "tiktok",
  "retryable": false
}

Codes we return before publishing

These are caught before anything is charged or published, so a post that fails them never costs a credit. Call POST /v1/posts/validate to get them without creating a post.

Codes the networks return

These come back after we have tried to publish. They carry a fix only where we can identify the error with confidence: an unrecognised rejection returns the network's own message and no advice, rather than a guess.

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.

A 403 that isn't from us

If you get a 403 whose body is a Cloudflare page mentioning error 1010, that is our edge rejecting the request before it reaches the API. It is not an authentication problem, so checking your key will not help.

The usual cause is Python's standard library: urllib.request sends User-Agent: Python-urllib/3.x, which the bot rules block. Set any other agent and it goes through:

req.add_header("User-Agent", "my-app/1.0")

requests, httpx, curl, fetch and the Go client all send their own agent and are unaffected.