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. These return a 4xx status and the envelope above. Deferred Meta advertising endpoints return 501 instead, as described below. 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:

Meta advertising features are deferred

The retained ad-account and branded-partner endpoints, Facebook Partnership Ads permission reads and actions, and Facebook branded-content post reads return HTTP 501 with the normal error envelope:

{
  "error": {
    "type": "not_implemented",
    "code": "meta_ads_deferred",
    "message": "Meta advertising features are deferred in PostLake. Ad-account and branded-partner lookups, Facebook Partnership Ads permissions, and Facebook branded-content post reads are unavailable. Reconnecting will not enable them.",
    "retryable": false
  }
}

What to do: do not retry or reconnect to enable these features. This is a PostLake feature deferral, not a missing-permission problem that a new connection can fix. Existing SDK methods remain available to call but return this error. Supported non-ad features, including organic publishing, analytics, ordinary tagged posts, and non-ad branded-content publishing, are unaffected.

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.