Start

Errors

The one error shape, every code in the catalogue, and what to do about each.

The shape#

Every error the public API raises itself has one body. code is stable for the life of v1 and is the thing to switch on; message is for a person; field names the offending input when there is one.

{
  "error": {
    "code": "SCHEDULED_TIME_IN_PAST",
    "message": "scheduledAt is 42 minutes in the past. Send a time in the future, or omit it to create a draft.",
    "field": "scheduledAt"
  }
}

Three families do not use this shape. Authentication and rate-limit failures answer with the flat body shown on Authentication and Rate limits. Schema validation of a request body (an unknown field, a wrong type, a missing required field) answers 400 with the framework's flat body: { "statusCode": 400, "message": ["..."], "error": "Bad Request" }. Unknown fields are refused, never ignored. And a post that breaks one target channel's limits on create or edit is refused by the shared publish checks, which answer 400 with a flat body carrying the code at the top level: { "statusCode": 400, "code": "TOO_LONG", "message": "X posts are limited to 280 characters (this one is 301)." }. Those codes are listed after the catalogue. Every flat body also carries error, path and timestamp beside the fields shown here; the examples on these pages list the fields worth switching on.

Warnings#

Things that happened without failing the call ride on successful writes as warnings: [{ code, message }]. Two exist: APPROVAL_REQUIRED (the post is queued as pending) and SCHEDULED_TIME_COERCED (a scheduledAt up to five minutes in the past was moved to now).

The catalogue#

Channel-limit refusals#

Every target of a post is checked against its channel's limits when the post is created or edited (POST /posts, PATCH /posts/:id, create_post, update_post). A failure answers 400 with the flat body { statusCode, code, message }; message names the channel and the cap, for example Bluesky takes either images or one video, not both in one post. Video size and duration are checked only when overads knows them from the file's media asset record; nothing is guessed from a URL.

Per-account failures are not errors#

A post to three accounts that lands on two answers 200. The account that failed is in targets with status: "failed" and the platform's error text verbatim in error. Read targets, not just the HTTP status, and subscribe to post.failed to be told.