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."
    ]
  }
}

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.

Status code reference

Status	Meaning	Typical cause
`200`	OK	Successful read or mutation.
`201`	Created	Resource created (some endpoints use `200` instead — both are success).
`204`	No Content	Successful delete or empty result.
`400`	Bad Request	Malformed JSON or missing required header.
`401`	Unauthenticated	Missing or invalid Bearer token.
`403`	Forbidden	Token lacks the required ability, or the user has no access to the workspace / resource.
`404`	Not Found	The resource doesn’t exist, has been deleted, or belongs to a workspace your token can’t see.
`409`	Conflict	The resource is in a state that prevents the action (e.g. editing a post that’s already `publishing`).
`422`	Unprocessable Entity	Validation failed. See the `errors` object for per-field details.
`429`	Too Many Requests	Rate limit hit. See Rate limits.
`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 given data was invalid.",
  "errors": {
    "publish_at": [
      "The publish at must be a date after now."
    ],
    "media_content_ids.0": [
      "The selected media content id is invalid."
    ]
  }
}

Use the errors object to display field-level messages in your UI. The numeric suffixes (e.g. media_content_ids.0) indicate which entry in an array failed validation.

Authentication errors

`message`	What to do
`Unauthenticated.`	The `Authorization` header is missing, malformed, or the token has been revoked. Re-check the header and generate a new token if needed.
`Invalid ability provided.`	The token is valid but doesn’t include the required ability for this endpoint. Create a new token with the right abilities in User Settings → Login & Security. See Authentication.
`This action is unauthorized.`	The user behind the token has no access to the target workspace or resource. Confirm membership in the dashboard.

Resource not found

Scenario	Status	Notes
The ID is a valid UUID format but doesn’t 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 can’t see.
The ID is malformed	`404`	Validation rejects non-UUID values for `{id}` path parameters.

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 (e.g. “Instagram: Media aspect ratio not supported”).

The HTTP response from the original create call was 200 — the failure is reported asynchronously. Always check status after creating a post, especially for scheduled posts that publish minutes or days after creation.

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.
`5xx`	Yes — with exponential backoff	Idempotent endpoints (`GET`, `PUT`, `DELETE`) are safe to retry blindly. For `POST` (which is non-idempotent), consider whether a duplicate is acceptable, or check whether the resource was created before retrying.

Reporting an error

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

The endpoint and method
The approximate timestamp (UTC)
The X-Request-Id header from the failing response, if present
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 errors

Resource not found

Publish failures

Retrying safely

Reporting an error

​Error envelope

​Status code reference

​Validation errors

​Authentication errors

​Resource not found

​Publish failures

​Retrying safely

​Reporting an error

Error envelope

Status code reference

Validation errors

Authentication errors

Resource not found

Publish failures

Retrying safely

Reporting an error