Errors

The API uses standard HTTP status codes and returns a consistent JSON error envelope.

Error envelope

{
  "message": "A human-readable description of what went wrong.",
  "errors": {
    "field_name": [
      "Specific validation message for this field."
    ]
  },
  "error_code": "MACHINE_READABLE_CODE"
}

message: always present. Safe to surface to end users.
errors: present on 422 validation failures. Each key is the offending field; each value is an array of per-field messages.
error_code: present on plan and ability errors. Current values are PLAN_UPGRADE_REQUIRED (with 402) and API_TOKEN_MISSING_SCOPE (with 403).

Status code reference

Status	Meaning	Typical cause
`200`	OK	Successful read, update, or delete. Deletes return `{"data": [], "message": "..."}` rather than `204`.
`201`	Created	Returned by `POST /workspaces/{workspace}/posts`, `POST /workspaces/{workspace}/media_contents` when the media is stored, and `POST /workspaces/{workspace}/media_library/folders`.
`202`	Accepted	Returned by `POST /workspaces/{workspace}/media_contents` when a URL import continues in the background. The item is `processing`; poll `GET /media_contents/{mediaContent}` until it is `active` or `failed`.
`401`	Unauthenticated	Missing or invalid Bearer token.
`402`	Payment Required	No plan behind the token includes the API, the workspace’s owner is on Free, or the workspace’s plan lacks the feature behind the endpoint (media library on Free; advanced analytics on Free and Pro).
`403`	Forbidden	Token lacks the required ability, the user has no access to the workspace or resource, or you tried to update a post that is already `published`.
`404`	Not Found	The resource does not exist, has been deleted, or belongs to a workspace your token cannot see.
`409`	Conflict	The resource’s state prevents the action: deleting a `published` post, or retrying a post that has not `failed`.
`413`	Content Too Large	A media upload over a size limit: a URL that announces more than 2 GB, or a file in `files[]` over 200 MB (use presign for it). See Upload and manage media. Not retryable as is.
`422`	Unprocessable Entity	Validation failed. See the `errors` object for per-field details.
`429`	Too Many Requests	Per-minute rate limit hit, or the daily post creation cap reached. See Rate limits.
`501`	Not Implemented	Direct uploads are not available for the server’s current storage driver. Not retryable.
`500`	Internal Server Error	Unexpected server error. Safe to retry with backoff.
`502 / 503 / 504`	Bad Gateway / Service Unavailable / Gateway Timeout	Transient infrastructure issue. Retry with exponential backoff.

Validation errors

The 422 shape mirrors Laravel’s validation output:

{
  "message": "The posts.0.scheduled for must be a date after or equal to now. (and 1 more error)",
  "errors": {
    "posts.0.scheduled_for": [
      "The posts.0.scheduled for must be a date after or equal to now."
    ],
    "posts.0.media_ids.0": [
      "The selected media is invalid or does not belong to this workspace."
    ]
  }
}

message is the first validation error. When there are more, it ends with how many, for example (and 1 more error) or (and 2 more errors). Use the errors object to display field-level messages in your UI. Keys mirror the request structure: posts.0.media_ids.0 means the first media ID of the first post item failed validation.

Authentication and plan errors

Status	`message`	What to do
`401`	`Unauthenticated.`	The `Authorization` header is missing, malformed, or the token has been revoked. Re-check the header and generate a new token if needed.
`402`	`API access is not included in your current plan. Please upgrade to continue.`	Neither the token’s user nor any workspace they belong to is on a plan that includes the API. Carries `"error_code": "PLAN_UPGRADE_REQUIRED"`. Upgrade to Pro or Business, or join a Pro or Business workspace.
`402`	`API access is not included in this workspace's plan. The workspace owner needs to upgrade to Pro or Business.`	The workspace belongs to an owner on Free. Same `error_code`. See Plans.
`402`	`Please upgrade your plan.`	The workspace’s plan lacks the feature behind this endpoint (media library, or advanced analytics for the analytics endpoints). Same `error_code`.
`403`	`The API token is missing a required ability for this endpoint: posts.`	The token is valid but does not include the required ability. Carries `"error_code": "API_TOKEN_MISSING_SCOPE"`. Create a new token with the right scopes in User Settings → Login & Security. See Authentication.
`403`	`This action is unauthorized.`	The user behind the token has no access to the target workspace or resource, or is trying to edit a published post. Confirm membership and role in the dashboard.

Resource not found

Scenario	Status	Notes
The ID is a valid UUID format but does not exist	`404`	The resource was deleted or never existed.
The ID belongs to a different workspace	`404`	We deliberately return 404 (not 403) here to avoid leaking the existence of resources in workspaces you cannot see.
The ID is malformed	`404`	Path parameters that are not UUIDs match nothing.

Post state errors

Posts move through a lifecycle, and some actions are only valid in some states:

Action	Post status	Response
`PUT /posts/{post}`	`published`	`403` `This action is unauthorized.`
`PUT /posts/{post}` with `scheduled_for` or `publish_type`	`publishing`	`422` `A post that is currently publishing cannot be rescheduled.`
`PUT /posts/{post}` with `status` `waiting` or `needs_approval`	`draft` with no profile	`422` `A post without a profile can only be saved as a draft.`
`DELETE /posts/{post}`	`published`	`409` `Only not published posts can be deleted.`
`PUT /posts/{post}/retry`	anything other than `failed`	`409` `Only failed posts can be retried.`

Publish failures

Posts that successfully reach the API but fail when handed off to the social network surface their error in two places:

The post’s status becomes failed.
error_message on the post contains the network’s error description (for example “Instagram: Media aspect ratio not supported”).

The HTTP response from the original create call was 201. The failure is reported asynchronously. Always check status after creating a post, especially for scheduled posts that publish minutes or days after creation. Failed posts can be re-attempted with PUT /posts/{post}/retry.

Retrying safely

Failure type	Safe to retry?	Notes
`4xx` (except `429`)	No	Fix the request before retrying.
`429`	Yes, after `Retry-After`	See Rate limits. The daily cap response has no `Retry-After`; wait for the window to roll.
`5xx`	Yes, with exponential backoff	Idempotent endpoints (`GET`, `PUT`, `DELETE`) are safe to retry blindly. `POST /workspaces/{workspace}/posts` is not idempotent: before retrying, list the workspace’s posts filtered by `filters[profile_ids][]` and check whether the batch was created.

Reporting an error

If you see consistent 5xx responses or behaviour that looks wrong, email hello@publishbuddy.com with:

The endpoint and method
The approximate timestamp (UTC)
The X-Request-ID header from the failing response (every response carries one)
A redacted dump of the request body (omit your token)

That gives us enough to find the request in our logs.

Getting started

Core concepts

How-to guides

API essentials

Error envelope

Status code reference

Validation errors

Authentication and plan errors

Resource not found

Post state errors

Publish failures

Retrying safely

Reporting an error

​Error envelope

​Status code reference

​Validation errors

​Authentication and plan errors

​Resource not found

​Post state errors

​Publish failures

​Retrying safely

​Reporting an error

Error envelope

Status code reference

Validation errors

Authentication and plan errors

Resource not found

Post state errors

Publish failures

Retrying safely

Reporting an error