*Social Media Manual — [index](../MANUAL.md)*

# 12. Error codes

Every `ok:false` reply carries `error.code`, a `message` for the user, `retryable`, a
`next_action` and sometimes `details`. This chapter lists every code the social tools answer.
JSON-RPC `-32602` (bad arguments) is not in this list: it means the call itself was malformed.

## Feature and identity

| code | meaning | next step |
|---|---|---|
| `SOCIAL_NOT_CONFIGURED` | the social feature is off on this server | use the other tools; the operator decides |
| `IDENTITY_REQUIRED` | no authenticated principal | connect the assistant through the consent page |
| `PLATFORM_UNSUPPORTED` | not a platform this server lists | `social_get_status` |
| `CONNECT_METHOD_UNSUPPORTED` | no browser flow for that platform | `social_connect_account` with a credential |

## Connecting

| code | meaning | next step |
|---|---|---|
| `CREDENTIAL_REQUIRED` | a credential field is missing | fields from `social_get_status` |
| `CONNECT_FAILED` | the platform rejected the credential (`retryable` when it was down) | fresh credential, or retry |
| `ACCOUNT_OWNED_ELSEWHERE` | another member already owns that platform account | ask that owner for an invitation |
| `INTENT_NOT_FOUND` | unknown or someone else's `intent_id` | `social_start_connect` again |
| `INTENT_PENDING` (retryable) | the user has not approved yet | ask them, then retry |
| `INTENT_EXPIRED` | 30 minutes passed | start again |
| `INTENT_FAILED` | the platform refused at sign-in (details) | start again; see chapter 14 for Meta app review |
| `RECONNECT_REQUIRED` | the account's credential is dead | the owner reconnects |

## Accounts, roles and sharing

| code | meaning | next step |
|---|---|---|
| `ACCOUNT_NOT_FOUND` | unknown, or not visible to you | `social_list_accounts` |
| `ACCOUNT_DISCONNECTED` | the account was disconnected | reconnect or drop it from the post |
| `ACCESS_DENIED` | your role is too low for this call | ask the owner |
| `ACCESS_REVOKED` | your access was revoked | ask the owner |
| `ACCESS_NOT_FOUND` | unknown `access_id` | `social_list_access` |
| `ROLE_INVALID` | role must be `editor` or `viewer` | fix the call |
| `EXPIRY_INVALID` | `expires_in_hours` out of range (1..336) | fix the call |
| `INVITATION_INVALID` | malformed claim token | check what the user pasted |
| `INVITATION_NOT_FOUND` | no such invitation | the owner creates a new one |
| `INVITATION_EXPIRED` | past its expiry | new invitation |
| `INVITATION_CLAIMED` | already used | new invitation |
| `INVITATION_SELF` | the owner is claiming their own token | nothing to do; they already own it |
| `MEMBER_NOT_FOUND` | `member_id` is not a member with access | `social_list_access` |

## Recovery

| code | meaning | next step |
|---|---|---|
| `RECOVERY_INVALID` | bad, used or expired code | mint a new one from the old session |
| `RECOVERY_CONFLICT` | this session already owns accounts | claim from a fresh session, before connecting |

## Media

| code | meaning | next step |
|---|---|---|
| `MEDIA_INVALID` | not valid base64 or not a recognisable file | check the upload |
| `MEDIA_TOO_LARGE` | over the server limit (25 MB default) or, at preview, over the platform's limit | smaller file |
| `MEDIA_UNSUPPORTED` | type not accepted (by the server, or at preview by the platform) | convert it (Instagram: JPEG) |
| `MEDIA_NOT_FOUND` | not your `media_id` | `social_list_media` |
| `MEDIA_UNAVAILABLE` | referenced media was deleted | replace it in the draft |

## Drafts and preview

| code | meaning | next step |
|---|---|---|
| `POST_NOT_FOUND` | unknown or not visible | `social_list_posts` |
| `POST_ARCHIVED` | the post is archived | create a new one |
| `POST_NOT_ON_ACCOUNT` | the post does not target that account, or you lack editor on a destination | fix `account_ids` |
| `REVISION_CONFLICT` | someone changed the post; `details.current_revision`, `details.current_text` | merge, call again |
| `CONTENT_INVALID` | a destination would reject the content; `details.errors` | `social_preview_post`, fix the draft |
| `CAPABILITY_UNSUPPORTED` | the platform cannot do that (video, several images, edit) | adjust, or delete and republish |

## Authorization

| code | meaning | next step |
|---|---|---|
| `AUTHORIZATION_REQUIRED` | you are not the owner and hold no matching authorization | the owner calls `social_grant_authorization` |
| `AUTHORIZATION_NOT_FOUND` | unknown `authorization_id` | `social_list_authorizations` |
| `AUTHORIZATION_REVOKED` | already revoked | nothing to do |

## Publishing and published posts

| code | meaning | next step |
|---|---|---|
| `PUBLICATION_NOT_FOUND` | unknown or not visible | `social_list_publications` |
| `NOT_PUBLISHED` | no live post for that publication on that account | `social_get_publication` |
| `RATE_LIMITED` (retryable) | the platform throttled | wait for the hint, or 15 minutes |
| `PLATFORM_UNAVAILABLE` (retryable) | 5xx or no connection | retry shortly |
| `PLATFORM_REJECTED` | the platform refused; message says why | fix the post or check the account |
| `PUBLICATION_OUTCOME_UNKNOWN` | no reply; attempt is `unknown` | chapter 7, reconciliation |

## Schedules and calendar

| code | meaning | next step |
|---|---|---|
| `SCHEDULE_NOT_FOUND` | unknown or not visible | `social_list_schedules` |
| `SCHEDULE_CANCELLED` | cancelled schedules cannot change | create a new one |
| `OCCURRENCE_NOT_FOUND` | unknown slot | `social_list_calendar` |
| `OCCURRENCE_LOCKED` | the slot is past, publishing or finished | pick another slot, or `social_publish_now` |

## Usage

| code | meaning | next step |
|---|---|---|
| `PERIOD_INVALID` | `from` / `to` not a date, or `from` after `to` | fix the period |