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
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
422 Unprocessable Entity	Validation failed	Missing required fields, invalid values
429 Too Many Requests	Rate limit hit	Reduce request frequency
500 Internal Server Error	Server error	Contact support

Handling in code

Python

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

Node.js

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.

Retrying on 429

When a 429 is returned, read the Retry-After response header and wait that many seconds before retrying:

Python

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

Node.js

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 Requests responses
• Authentication — fix 401 and 403 responses