Error Handling
PostBoost uses standard HTTP status codes and returns consistent JSON error bodies.
Error format
All errors return a JSON object with at minimum a message field:
{
"message": "Validation errors.",
"errors": {
"versions": ["The versions field is required."],
"accounts.0": ["The selected account is invalid."]
}
}
Status codes
| Code | Meaning | Common cause |
|---|---|---|
400 Bad Request | Invalid request | Trying to delete your own account; attempting to edit a published post |
400 Bad Request | Invalid Idempotency-Key | Use 1–255 printable ASCII characters, for example a UUID |
401 Unauthenticated | Missing or invalid token | No Authorization header, expired token |
403 Forbidden | Insufficient permissions | Token lacks admin rights for panel endpoints |
404 Not Found | Resource not found | Wrong workspace UUID, deleted post |
409 Conflict | Duplicate post, or same Idempotency-Key still in progress | See guardrail errors |
422 Unprocessable Entity | Validation failed | Missing required fields, invalid values, account must be reconnected |
429 Too Many Requests | Rate limit hit, or an account's daily post cap reached | Reduce request frequency; see guardrail errors |
500 Internal Server Error | Server error | Contact support |
Handling in code
- Python
- Node.js
response = requests.post(url, headers=headers, json=data)
if response.status_code == 422:
errors = response.json().get("errors", {})
for field, messages in errors.items():
print(f"{field}: {', '.join(messages)}")
elif response.status_code == 401:
print("Invalid API token — check your credentials")
elif not response.ok:
print(f"Error {response.status_code}: {response.json().get('message')}")
else:
post = response.json()
const res = await fetch(url, { method: "POST", headers, body });
const data = await res.json();
if (!res.ok) {
if (res.status === 422) {
console.error("Validation errors:", data.errors);
} else {
console.error(`Error ${res.status}:`, data.message);
}
throw new Error(data.message);
}
Validation errors
422 responses include an errors object mapping field names to arrays of error messages. Field names use dot notation for nested objects:
{
"message": "Validation errors.",
"errors": {
"versions": ["The versions field is required."],
"versions.0.is_original": ["The is_original field must be true for the first version."],
"date": ["The date does not match the format Y-m-d."]
}
}
Common mistakes
422 — Post creation failures
| Error message | Cause | Fix |
|---|---|---|
The versions field is required. | No versions array in the request body | Add at least one PostVersion object |
At least one version with is_original: true is required. | No version marked as original | Set is_original: true on exactly one version |
The date does not match the format Y-m-d. | Wrong date format for scheduled posts | Use YYYY-MM-DD, e.g. "2026-06-15" |
The selected account is invalid. | Account ID not in this workspace | Call GET /{workspaceUuid}/accounts to get valid IDs |
400 — Modifying a published post
Attempting to update or delete a post that has already been published returns a 400 Bad Request. Check the post's status field before mutating it. Published posts cannot be edited — create a new post instead.
Guardrail errors
Create and update requests from the API carry a code when a guardrail refuses them:
| Status | code | Meaning | Fix |
|---|---|---|---|
409 | duplicate_post | Same content for this account in the last 24 hours; existing_post_uuid names the earlier post | Change the content, or send "allow_duplicate": true |
429 | account_daily_cap_reached | The account reached its daily post cap on that UTC day (limit, used) | Schedule for another day |
422 | account_unauthorized | The account must be reconnected | Reconnect it in the dashboard |
422 | account_token_missing | The account has no access token | Reconnect it in the dashboard |
Check a post before creating it with POST /{workspaceUuid}/posts/validate.
Idempotent requests
Send an Idempotency-Key header with a POST to make it safe to retry after a timeout or a dropped connection. The same key with the same body within 24 hours returns the original response with Idempotent-Replayed: true and creates nothing new.
curl -X POST https://postboost.co/app/api/$WORKSPACE/posts \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: 6f1c0a52-8d2e-4f7b-9d61-0c4b2a7e9f33" \
-d '{"accounts":[12],"schedule_now":true,"versions":[{"account_id":0,"is_original":true,"content":[{"body":"Hello"}]}]}'
Reusing a key with a different body returns 422; a request still running with the same key returns 409 with Retry-After: 1. 5xx and 429 responses are not stored, so retry them with the same key.
Retrying on 429
When a 429 is returned, read the Retry-After response header and wait that many seconds before retrying:
- Python
- Node.js
import time, requests
def post_with_retry(url, headers, data, max_retries=3):
for attempt in range(max_retries):
response = requests.post(url, headers=headers, json=data)
if response.status_code == 429:
wait = int(response.headers.get("Retry-After", 5))
time.sleep(wait)
continue
return response
raise Exception("Max retries exceeded")
async function postWithRetry(url, options, maxRetries = 3) {
for (let i = 0; i < maxRetries; i++) {
const res = await fetch(url, options);
if (res.status === 429) {
const wait = parseInt(res.headers.get('Retry-After') ?? '5', 10);
await new Promise(r => setTimeout(r, wait * 1000));
continue;
}
return res;
}
throw new Error('Max retries exceeded');
}
See also
- Rate Limits — handle
429 Too Many Requestsresponses - Authentication — fix
401and403responses - Network permissions status — features that depend on a network's app review (for example, first comments on Facebook and Instagram)
- Agent Guardrails — dry runs, duplicate guard, daily caps, activity log