Skip to main content

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​

CodeMeaningCommon cause
400 Bad RequestInvalid requestTrying to delete your own account; attempting to edit a published post
400 Bad RequestInvalid Idempotency-KeyUse 1–255 printable ASCII characters, for example a UUID
401 UnauthenticatedMissing or invalid tokenNo Authorization header, expired token
403 ForbiddenInsufficient permissionsToken lacks admin rights for panel endpoints
404 Not FoundResource not foundWrong workspace UUID, deleted post
409 ConflictDuplicate post, or same Idempotency-Key still in progressSee guardrail errors
422 Unprocessable EntityValidation failedMissing required fields, invalid values, account must be reconnected
429 Too Many RequestsRate limit hit, or an account's daily post cap reachedReduce request frequency; see guardrail errors
500 Internal Server ErrorServer errorContact support

Handling in code​

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()

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 messageCauseFix
The versions field is required.No versions array in the request bodyAdd at least one PostVersion object
At least one version with is_original: true is required.No version marked as originalSet is_original: true on exactly one version
The date does not match the format Y-m-d.Wrong date format for scheduled postsUse YYYY-MM-DD, e.g. "2026-06-15"
The selected account is invalid.Account ID not in this workspaceCall 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:

StatuscodeMeaningFix
409duplicate_postSame content for this account in the last 24 hours; existing_post_uuid names the earlier postChange the content, or send "allow_duplicate": true
429account_daily_cap_reachedThe account reached its daily post cap on that UTC day (limit, used)Schedule for another day
422account_unauthorizedThe account must be reconnectedReconnect it in the dashboard
422account_token_missingThe account has no access tokenReconnect 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:

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")

See also​