invalid_grantReconnectThe Mastodon OAuth grant is invalid, expired, or revoked.
Reconnect the account on the user's Mastodon instance.
refresh-token
Error reference
Mastodon API errors and troubleshooting
Understand Mastodon API errors across OAuth, instance availability, disabled users, unconfirmed accounts, validation, federation, object storage, SSL checks, and rate limits. Use this page to decide whether to reconnect, simplify a status, check the user's instance, or retry later.
Last updated: May 2026
Error desk
8 mapped failures
8 documented error patterns across 7 categories
Clear guidance on reconnecting, retrying, replacing media, or changing content
Official platform references plus bundle.social production troubleshooting notes
Error categories
Find the failure type first
8 documented errors
All error codes
Codes, causes, and fixes
Authentication
2 mapped cases
401ReconnectThe endpoint requires an authenticated user.
Reconnect or send a valid user token for the selected instance.
refresh-token
Request
1 mapped case
400Fix inputMastodon rejected a malformed request.
Check required parameters and instance-specific API expectations.
user-error
Permissions
1 mapped case
403Fix inputThe action is not allowed for this account.
Check disabled, unconfirmed, pending approval, blocked, or role-restricted account status.
user-error
Not Found
1 mapped case
404Fix inputThe requested Mastodon record was not found or is not visible.
Refresh IDs and confirm the authorized user can access the object.
user-error
Validation
1 mapped case
422Fix inputMastodon could not create or update the entity.
Simplify the status, poll, media, or scheduled post payload and retry.
user-error
Rate Limiting
1 mapped case
429Retry laterThe Mastodon instance rate limited the request.
Wait for the instance limit to reset before retrying.
retry
Remote Service
1 mapped case
503Retry laterA remote service, object storage, SSL check, or federation request failed.
Retry later because the issue may be instance or remote-service availability.
retry
Unauthorized or forbidden
Secure-mode instances, disabled users, unconfirmed emails, and moderation restrictions can block API calls.
Unprocessable entity
A 422 usually means the status, media, poll, or account action failed validation on that specific instance.
Mastodon errors vary by instance
Mastodon is federated, so API behavior depends on the user's instance version, local moderation rules, storage provider, SSL setup, rate limits, account state, and federation availability.
A valid request can still fail on one specific instance
A status, media upload, poll, or scheduled post can work on one Mastodon instance and fail on another. Check the instance response, account state, and local validation rules before treating it as a generic API error.
How bundle.social helps
bundle.social groups Mastodon publishing failures by instance auth, account status, request validation, media or poll payloads, rate limits, object storage, SSL, and federation availability.
Retry safety
Retry only temporary platform failures, processing delays, timeouts, 5xx responses, and rate-limit errors after the platform allows it. Do not retry the same request when the failure is caused by expired tokens, missing permissions, unsupported media, invalid captions, duplicate content, account restrictions, or policy blocks. The same payload will usually fail again until the account, media, content, or platform-specific setting is fixed.
Official references
Platform APIs change. Use these links to confirm current error behavior and field support.
FAQ
Can Mastodon API error messages change over time?
Mastodon behavior varies by instance version, moderation settings, federation state, storage provider, and local policy. Interpret HTTP statuses with the user's instance context.
Should users reconnect the account for every failed post?
No. Reconnect Mastodon for invalid grants or authentication failures. For 422 validation, 403 account restrictions, 429 rate limits, or 503 remote-service issues, fix the status or wait for the instance to recover.
Does bundle.social hide the native platform error?
bundle.social keeps the instance response for support and helps distinguish OAuth failures from local moderation, validation, remote-service, and federation problems.
Related
Keep researching
Build with less platform drag