Errors
What a refusal looks like
A refusal is an RFC 9457 problem+json body. Branch on code, never on message; extra fields (hint, issues, reset_at) say how to recover.
application/problem+json
{
"type": "https://postory.io/docs/api/errors#scope_required",
"title": "Scope required",
"status": 403,
"code": "scope_required",
"message": "This API key does not have the \"Publish & schedule posts to your connected accounts\" permission. Create a new key with it in Postory under Settings → API keys, and use that key.",
"required_scope": "postory:publish"
}Codes by status
Every code
- 402
credit_limit - Not enough credits for this action. Buy credits in Postory (buy_url), then retry.
- 403
access_paused - AI access is paused for this Postory account. Resume it in AI apps.
- 403
account_blocked - This Postory account cannot publish or edit right now. Contact support.
- 403
app_disconnected - The key or AI app was revoked or disconnected. Create a new key or reconnect the app.
- 403
app_paused - This key or app is paused. Resume it in AI apps.
- 403
email_unverified - The Postory account's email is not verified. Verify it in Postory, then retry.
- 403
forbidden - This key may not act on that object. Check that you use the right account's key.
- 403
insufficient_scope - The key or app no longer has the permission this call needs. Grant it in AI apps or use another key.
- 403
plan_required - The current plan does not include this feature. Upgrade in Postory.
- 403
private_address - Postory will not fetch that URL (a private or local address). Use a public https URL.
- 403
read_only - The Postory account is read-only and cannot import. Subscribe to import again.
- 403
scope_required - The key lacks the permission this call needs (required_scope). Create a key that has it.
- 403
subscription_required - The current plan does not include this. Upgrade in Postory.
- 404
account_gone - The Postory account no longer exists. Stop using this key.
- 404
account_not_found - No connected social account with that id. List accounts for current ids.
- 404
media_folder_not_found - No media-library folder has that id or name. Name one from folders by id or name, or root for files in no folder.
- 404
media_not_found - No media with that id on the post. Read the draft for current media ids.
- 404
not_found - Nothing with that id on this account. Check the id.
- 404
post_not_found - No post or draft with that id on this account. List drafts for a current id.
- 405
method_not_allowed - The route does not take that HTTP method. Use one that the Allow header lists.
- 409
account_choice_required - Several accounts fit and none was named. Ask the user which one and pass its connection_id.
- 409
already_finished - That run has already finished. There is nothing to do.
- 409
already_published - The post is already published. There is nothing to do.
- 409
already_publishing - This post is being published now. Wait, then read its delivery.
- 409
already_running - The same run is already in progress. Wait for it and read its result.
- 409
already_scheduled - This post already has a delivery queued for that account. Reschedule that delivery instead.
- 409
approval_pending - The user has not approved it in the browser yet. Keep the token and call again after their approval.
- 409
browser_approval_required - This account approves every publish in Postory. Send the user to approval_url.
- 409
confirmation_expired - The confirmation token expired. Preview again for a new one.
- 409
confirmation_mismatch - The token was issued for something else. Preview this action again.
- 409
conflict - The post's state does not allow this (for example, it is scheduled). Read it and act on its current state.
- 409
connection_suspended - The social account is paused because the plan's account limit is exceeded. Upgrade or remove an account.
- 409
daily_post_limit - This account has posted as much as it may in 24 hours. Schedule the post at or after next_allowed_at; there is no Retry-After and no override.
- 409
delivery_changed - The delivery changed while it was being moved. Read it again and retry.
- 409
draft_archived - The draft is archived. Restore it from the Archive in Postory (Calendar → List), then schedule it.
- 409
draft_changed - The draft changed after the preview, so nothing was published. Preview it again and show the new preview.
- 409
duplicate_content - The same text was posted on this account too recently. Change the text or schedule it after next_allowed_at.
- 409
idempotency_conflict - That Idempotency-Key was used with a different request. Use a new key for a new request.
- 409
import_active - An import is already running for this account. Wait for it to finish.
- 409
no_account - No social account is connected. Connect one in Postory (connect_url).
- 409
no_x_account - This needs an X account and none is connected. Connect one in Postory.
- 409
partial_delivery - This delivery already has live thread parts. Finish that delivery instead of starting a new one.
- 409
posting_too_often - This account posted less than 10 minutes ago. Schedule the post at or after next_allowed_at; there is no Retry-After and no override.
- 409
quote_changed - The price changed after the preview. Get a new quote and ask the user again.
- 409
reconnect_required - The social account's authorization is no longer valid. Reconnect it in Postory.
- 409
reply_already_answered - That reply already has an answer. There is nothing to do.
- 409
reply_daily_limit - This account has replied as much as it may in 24 hours. Send the replies again at or after next_allowed_at.
- 409
reply_one_at_a_time - A reply post is scheduled on its own, never in a batch. Send it in its own call.
- 409
replying_too_often - This account replied less than a minute ago. Retry at next_allowed_at; there is no Retry-After and no override.
- 409
unsupported_platform - This action is not available on that network. Use an X, Threads or Bluesky account.
- 410
media_expired - The saved media link expired. Upload the file again.
- 410
upload_link_expired - The upload link expired before the file arrived. Ask for a new link and upload again.
- 410
upload_not_found - No file arrived at the upload URL. PUT the file there first, then attach it.
- 411
length_required - The upload had no size. Send it again with a Content-Length header.
- 413
too_large - The file is too large for the network. Send a smaller file.
- 413
video_size_limit - The video is over your plan's size limit; the message names it. Upload a smaller one.
- 415
not_an_image - That file is not an image. Send an image file.
- 415
unsupported_media_type - That file type is not accepted. Send a supported image or video type.
- 422
bad_cursor - The cursor is unknown or expired. Drop it and list again from the start.
- 422
capability_unsupported - The account's network does not take what the post asks (capability names it: a first comment on LinkedIn). Remove it for that account, or post to an account whose network takes it.
- 422
empty_file - The uploaded file is empty. Upload it again.
- 422
invalid_argument - A value is malformed or out of its window (an id that is not a UUID, scheduled_at outside 2 minutes–30 days). The message names the field.
- 422
media_folder_ambiguous - Two or more media-library folders have that name. Name one by its id from folders.
- 422
not_a_web_url - The value is not an http(s) link. Upload the file instead with POST /api/v1/media.
- 422
parameter_retired - That parameter is no longer accepted. Drop it; the message names what replaced it.
- 422
part_out_of_range - The draft has no part with that number. Read the draft and use an existing part.
- 422
preflight_failed - The post cannot be published or scheduled as it is. Fix what issues lists, then retry.
- 422
profile_private - The X account is protected; only public accounts can be checked by handle. Use a public account.
- 422
unreachable_url - Postory could not download that URL. Check that it is public and answers, or upload the file.
- 422
validation_failed - A field is missing, unknown or the wrong type, or the post breaks a network rule (length, media, thread). Fix what issues lists and send it again.
- 429
media_library_full - The media library has no room for the file (metric: library_files or library_bytes, with current and limit). The user deletes files in Postory (library_url), then retries.
- 429
publishing_limit - Your plan's direct publishes for this billing period are used. Retry after Retry-After, when the new period starts, or upgrade.
- 429
rate_limited - Over a rate limit. Wait the Retry-After seconds, then retry.
- 429
scheduled_posts_limit - Your plan's scheduled posts for this billing period are used. Retry after Retry-After, when the new period starts, or upgrade.
- 429
upload_bytes_daily_limit - Your uploads of the last 24 hours reached your plan's cap. Retry after Retry-After, as the oldest upload ages out, or upgrade.
- 500
internal_error - Something failed on Postory's side. Retry; if it repeats, contact support.
- 503
provider_busy - A data provider is busy or at capacity. Nothing was charged; retry later.
- 503
publish_disabled - Publishing through AI apps and the API is switched off for now. Retry later.
- 503
writes_disabled - Writes through AI apps and the API are switched off for now. Reading still works; retry later.
- 504
timeout - The call took too long. Read the current state before you retry a write.
social_account_limit