Errors and rate limits

Status codes

200

OK

It worked.

201

Created

The post or media was created; it’s in the response.

204

No content

It was deleted. There’s no body.

401

Unauthorized

The key is missing, revoked, or its owner left the workspace.

403

Forbidden

The key is read only, your role doesn’t allow it, the post can’t change any more, or the workspace owner’s plan has ended.

404

Not found

Nothing with that id in the key’s workspace.

422

Unprocessable

The request didn’t pass validation, for example a post over a network’s limit.

429

Too many requests

Slow down: wait for the seconds in Retry-After.

5xx

Server error

Something failed on our side. Retry with a backoff; it’s safe for reads and deletes.

Error body

Every error has a message. Errors you might want to handle in code also have a code:

{
  "message": "This API key is read only. Create a read and write key to make changes.",
  "code": "read_only_key"
}

• invalid_api_key: the key is missing, wrong or revoked, or its owner left the workspace.
• read_only_key: the key can’t make changes.
• subscription_required: the workspace owner’s plan has ended. The API works again once they choose a plan.
• account_suspended and email_unverified: the key’s owner must sort out their account first.

Validation errors

A 422 lists what’s wrong per field, using the field’s path in your request. Network limits are checked for every channel, and the message names the channel:

{
  "message": "Bluesky (Acme): allows at most 300 characters.",
  "errors": {
    "targets.1.content": ["Bluesky (Acme): allows at most 300 characters."]
  }
}

Drafts are saved even when they don’t fit a network yet; the checks run when you schedule.

Rate limits

Each key can make 120 requests a minute, and media uploads are limited to 30 a minute. Over the limit, you get a 429 with a Retry-After header in seconds. Responses also carry X-RateLimit-Limit and X-RateLimit-Remaining, so you can slow down before you hit it.