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. |
| 403 | BLOCKED | The user is blocked; contact Posteady support. |
| 403 | PLAN_REQUIRED | Use an eligible Creator-or-above workspace. |
| 403 | INSUFFICIENT_PERMISSION | Ask the workspace owner to review your current operation permission. |
| 404 | ACCOUNT_NOT_FOUND / POST_NOT_FOUND | Check the ID and the key’s workspace. The resource may no longer be available. |
| 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 requests and wait for the rate-limit window. |
| 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 | New Facebook writes are temporarily unavailable; existing job operations remain available. |
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 accounts or 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.
Job states · Retry guidance · Limits