Errors
The error format and what the most common codes mean.
{
"error": {
"code": "caption_too_long",
"message": "Threads allows at most 500 characters",
"details": { "platform": "threads", "account_id": "b2.." }
}
}code is stable and safe to use in your code. message can change.
| HTTP | Codes |
|---|---|
| 400 | validation_failed, caption_too_long, media_required, media_invalid_format, too_many_media, invalid_options, option_requires_text_only, too_many_links |
| 401 | unauthenticated, invalid_api_key, invalid_token |
| 403 | insufficient_scope (the key only has read access), email_not_verified, plan_required, plan_account_limit, plan_post_quota (see Plans & limits) |
| 404 | not_found |
| 409 | idempotency_conflict, post_not_editable, post_not_removable, media_in_use |
| 422 | account_expired (reconnect the account), account_plan_inactive (the account is deactivated by the plan limit), publishing_limit_reached, permission_missing |
| 429 | rate_limited |
| 422 | A permanent refusal from the platform with its own code (e.g. permission_missing, platform_error). Previously 502; changed because Cloudflare replaces 502 bodies with an HTML page |
Why a post failed
Each post target has an error_code when it fails to publish, such as account_expired, permission_missing, rate_limited, media_fetch_failed, image_too_large, aspect_ratio_invalid, caption_too_long, or publish_limit_reached. error_message holds Meta's original message.
While waiting for a platform limit, the target stays pending with a waiting error_code and retry_after set to the next attempt, for example youtube_quota_waiting, tiktok_daily_limit_waiting, rate_limited_waiting, or publish_paced (Tebar spaces out posts to the same TikTok or Threads account, see Limitations). The post goes out by itself, with nothing to do.
Temporary errors from Meta are retried automatically. For the others, fix the cause and then call POST /v1/posts/{id}/retry.