Posteady
Posteady Docs
User guideDeveloper guidesAPI referenceMCP

Errors and partial failures

Read error messages and per-account results to choose the next action.

Error format

A rejected request uses this common error envelope. Read message as well as the code.

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Missing or invalid API key."
  }
}

Status codes

HTTPCodeNext step
401UNAUTHENTICATEDCheck the Bearer header and whether the key was revoked.
402INSUFFICIENT_CREDITSThe organization does not have enough credits. Check or add credits in Posteady.
403BLOCKEDThe user is blocked; contact Posteady support.
403PLAN_REQUIREDUse a workspace on the Creator plan or higher.
403INSUFFICIENT_PERMISSIONAsk a workspace admin to check your permissions for this operation.
404ACCOUNT_NOT_FOUND / POST_NOT_FOUNDCheck the ID and the key’s workspace. The resource may no longer be available.
404CAROUSEL_NOT_FOUNDCheck the carouselId and the key’s workspace.
404COMMENT_NOT_FOUNDUse the commentId and accountId from the comments list. The comment may have been deleted.
409ACCOUNT_TOKEN_EXPIREDReconnect the social account in Posteady.
409ALREADY_REPOSTEDThe source was already reposted. Do not repeat it.
409REQUEST_CONFLICTUse the saved input for the same requestId; use a new ID only for a new operation.
409POST_NOT_CANCELLABLESubmission has started or the job cannot be canceled. Check its status.
422VALIDATION_ERRORRead the message and compare the input with the platform schema.
429RATE_LIMITEDSpace out your requests and wait for the rate-limit window to reset.
429QUOTA_EXCEEDEDRead the message to distinguish monthly usage from media storage.
500INTERNAL_ERRORAn unexpected server failure occurred. For writes, inspect the outcome before retrying.
502PLATFORM_ERRORThe platform rejected an operation; inspect the message and account connection.
503SERVICE_UNAVAILABLEPosteady could not reach a platform or finish a check. Read the message to see whether anything was posted, then retry later.

Partial failures

Publishing and scheduling can report per-account failures in results instead of a top-level error. A text request with at least one successful account returns HTTP 200 like this:

{
  "results": [
    {
      "accountId": "11111111-1111-4111-8111-111111111111",
      "provider": "threads",
      "username": "example",
      "success": true,
      "postIds": [
        "18000000000000000"
      ]
    },
    {
      "accountId": "77777777-7777-4777-8777-777777777777",
      "provider": "x",
      "username": "example_x",
      "success": false,
      "postIds": [],
      "error": "Example platform failure"
    }
  ],
  "summary": {
    "succeeded": 1,
    "failed": 1
  }
}

If all text targets fail, the response uses HTTP 502 with the same result shape. Inspect success, postIds, and error, and avoid republishing to accounts, or republishing chain entries, that already succeeded.

Asynchronous job errors

A job can fail after HTTP 202. Read status, error.code, and error.message from GET /publish-jobs/{id}. Job error codes can differ from the HTTP error table. A terminal Facebook replay returns HTTP 200 even on failure, so inspect both success and status.

If the workspace turned on approvals, a job for a post that was not approved by its scheduled time fails with APPROVAL_REQUIRED. With approvals on, only someone assigned to every step can publish immediately. Anyone else gets INSUFFICIENT_PERMISSION. Schedule the post and get it approved.

Job states · Retry guidance · Limits

More related guides

On this page