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
| HTTP | Code | Next step |
|---|---|---|
| 401 | UNAUTHENTICATED | Check the Bearer header and whether the key was revoked. |
| 402 | INSUFFICIENT_CREDITS | The organization does not have enough credits. Check or add credits in Posteady. |
| 403 | BLOCKED | The user is blocked; contact Posteady support. |
| 403 | PLAN_REQUIRED | Use a workspace on the Creator plan or higher. |
| 403 | INSUFFICIENT_PERMISSION | Ask a workspace admin to check your permissions for this operation. |
| 404 | ACCOUNT_NOT_FOUND / POST_NOT_FOUND | Check the ID and the key’s workspace. The resource may no longer be available. |
| 404 | CAROUSEL_NOT_FOUND | Check the carouselId and the key’s workspace. |
| 404 | COMMENT_NOT_FOUND | Use the commentId and accountId from the comments list. The comment may have been deleted. |
| 409 | ACCOUNT_TOKEN_EXPIRED | Reconnect the social account in Posteady. |
| 409 | ALREADY_REPOSTED | The source was already reposted. Do not repeat it. |
| 409 | REQUEST_CONFLICT | Use the saved input for the same requestId; use a new ID only for a new operation. |
| 409 | POST_NOT_CANCELLABLE | Submission has started or the job cannot be canceled. Check its status. |
| 422 | VALIDATION_ERROR | Read the message and compare the input with the platform schema. |
| 429 | RATE_LIMITED | Space out your requests and wait for the rate-limit window to reset. |
| 429 | QUOTA_EXCEEDED | Read the message to distinguish monthly usage from media storage. |
| 500 | INTERNAL_ERROR | An unexpected server failure occurred. For writes, inspect the outcome before retrying. |
| 502 | PLATFORM_ERROR | The platform rejected an operation; inspect the message and account connection. |
| 503 | SERVICE_UNAVAILABLE | Posteady 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