Bluesky API errors
Bluesky API errors arise when publishing through the AT Protocol and the Bluesky PDS. Session-based authentication and grapheme-based length limits make these failures look different from errors on other platforms. This guide covers 10 documented errors across authentication, rate limit, moderation, media, and content, so you can identify the category first and apply the correct fix without unsafe retries.
Bluesky API errors: how to identify the failure category
Bluesky uses session-based authentication rather than OAuth, and its post length limit is based on graphemes rather than bytes. That combination explains most of the error shapes you will see when publishing. Before retrying anything, classify the failure: a 401 points to authentication, a 429 points to rate limiting, and a successful request that is still rejected points to moderation, media, or content rules. Retrying a moderation, media, or content rejection without changing the post will reproduce the same result, while retrying an authentication failure without a fresh session will also fail. The sections below follow that order, and the quick reference table at the end collects all 10 codes in one place.
Authentication errors: invalid token, expired, unauthorized
An invalid token error (HTTP 401) means the Bluesky session token is no longer valid. Bluesky uses short-lived session tokens, so calls fail when no recent refresh has occurred. The fix is to reconnect by creating a new session with the user's handle and an app password. An expired error (HTTP 401) means the session aged past its time to live because no refresh call reached it in time; recreate the session. An unauthorized error (HTTP 401) means Bluesky rejected the auth header, which happens when the token was revoked, the password was rotated, or the app password was deleted. In that case, ask the account owner to create a fresh app password via bsky.app/settings/app-passwords, then reconnect with it. In all three cases, the failure check is the same: confirm whether the session is fresh and whether the app password still exists before attempting another publish.
Rate limit errors: rate limit and too many requests
A rate limit error (HTTP 429) means Bluesky throttled the request, typically after a burst of writes against the PDS. The practical fix is to wait a few minutes and spread out batch posting rather than submitting the same batch again immediately. A too many requests error (HTTP 429) means a per-user or per-IP rate cap was hit, usually from a sustained high request rate. Back off exponentially in that case, and respect the RateLimit-Reset header when it is present so the next attempt is timed to the reset rather than to a fixed guess. Do not treat a 429 as a content or authentication problem: changing the post text or reconnecting the account will not clear a rate limit, and immediate retries can keep you throttled.
Moderation errors: blocked and moderation
A blocked error means Bluesky moderation blocked the post because AT Protocol moderation labellers flagged the content as policy-violating. Review Bluesky's community guidelines and rewrite the post; resending the same content unchanged will not help. A moderation error is a generic moderation rejection, which happens when content matches a moderation filter, such as spam, harassment, or NSFW content without a label. If the post is legitimate NSFW content, apply the appropriate self-label; otherwise rewrite it. Before retrying either error, check whether the issue is the content itself or a missing label, because those two causes have different fixes.
Media errors: blob too large and blob invalid
A blob too large error means the image exceeds Bluesky's 1MB blob cap. The AT Protocol enforces a strict 1MB per blob limit for images, so compress the image aggressively before publishing; Bluesky is unusually strict here compared with many other platforms. A blob invalid error means the media file is corrupted or not a supported format. Bluesky accepts JPG, PNG, and WebP for images, so re-export the file from the source in one of those formats. The failure check is straightforward: verify the file's byte size against the 1MB cap and confirm its format is JPG, PNG, or WebP before retrying.
Content error: text too long and the 300 grapheme limit
A text too long error means the post text exceeds 300 graphemes. Bluesky's 300-character limit is grapheme-based, not byte-based, so a byte count or a simple character count can give the wrong answer for text containing emoji or combined characters. Trim the post or chain it into a thread of shorter posts. Pre-validate the grapheme count before publishing, and treat any post at or near the limit as a candidate for splitting rather than retrying unchanged.
Quick reference and pre-publish checklist
Use the quick reference table below to look up any of the 10 codes by name. The worked pre-publish validation example shows how to check grapheme length, image size and format, and session freshness together before you publish. For rate limits, the safe retry rule is to wait, back off exponentially, and honor the RateLimit-Reset header when present. For authentication failures, reconnect with a fresh session and a current app password. For moderation, media, and content failures, change the post itself — its wording, labels, image size, image format, or length — before trying again.
| Code | Category | HTTP status | What it means | Cause | Fix |
|---|---|---|---|---|---|
| invalid token | Authentication | 401 | Bluesky session token is no longer valid. | Short-lived session tokens without a recent refresh. | Reconnect by creating a new session with the user's handle and an app password. |
| expired | Authentication | 401 | Session aged past its TTL. | No refresh call hit the session in time. | Recreate the session. |
| unauthorized | Authentication | 401 | Bluesky rejected the auth header. | Token revoked, password rotated, or app password deleted. | Ask the account owner to create a fresh app password via bsky.app/settings/app-passwords, then reconnect. |
| rate limit | Rate limit | 429 | Bluesky throttled the request. | Burst of writes against the PDS. | Wait a few minutes; spread out batch posting. |
| too many requests | Rate limit | 429 | Per-user or per-IP rate cap hit. | Sustained high request rate. | Back off exponentially; respect the RateLimit-Reset header. |
| blocked | Moderation | Not supplied | Bluesky moderation blocked the post. | AT Protocol moderation labellers flagged content as policy-violating. | Review Bluesky's community guidelines and rewrite the post. |
| moderation | Moderation | Not supplied | Generic moderation rejection. | Content matched a moderation filter (spam, harassment, NSFW without label). | Apply the appropriate self-label for legitimate NSFW content; otherwise rewrite. |
| blob too large | Media | Not supplied | Image exceeds Bluesky's 1MB blob cap. | AT Protocol enforces a strict 1MB per blob for images. | Compress the image down to 1MB or below. |
| blob invalid | Media | Not supplied | Media file is corrupted or not a supported format. | Bluesky accepts JPG, PNG, and WebP for images. | Re-export from the source in a supported format. |
| text too long | Content | Not supplied | Post text exceeds 300 graphemes. | Bluesky's limit is grapheme-based, not byte-based. | Trim the post or chain posts in a thread; pre-validate the grapheme count. |
HTTP status shown only where supplied in the source; moderation, media, and content rows had no status in the source.
Frequently asked questions
How do I decide whether to reconnect, wait, or rewrite a Bluesky post?
Check the HTTP status and code first. A 401 such as invalid token, expired, or unauthorized points to a stale or revoked session, so recreate the session with a current app password. A 429 such as rate limit or too many requests points to throttling, so wait, back off exponentially, and honor RateLimit-Reset when present. Moderation, media, and content rejections require changing the post itself before retrying.
Why did a post fail as text too long when it looked short enough?
Bluesky counts graphemes, not bytes, with a limit of 300 graphemes. Text with emoji or combined characters can pass a byte or simple character count and still fail, so count grapheme clusters before publishing and trim or split into a thread when the count is over the limit.
What should I check for blob too large and blob invalid errors?
Verify the image is no larger than the 1MB blob cap and is in JPG, PNG, or WebP format. If it is too large, compress it; if it is corrupted or in another format, re-export it from the source in a supported format before retrying.