> ## Documentation Index
> Fetch the complete documentation index at: https://docs.sharedgraph.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and client reactions

> Handle domain refusals, OAuth errors and temporary unavailability.

Core errors use an `error` machine identifier, with optional diagnostic fields. OAuth errors may include `error_description`; provider browser helpers can instead return `code` and `message`. Match the machine identifier, not diagnostic prose. The starter wraps some refusals in its own user-facing `error` text; do not parse that text as a core error code. The generated API reference defines each operation's response shapes and status codes.

| Status | Client reaction |
| - | - |
| 400 | Fix request fields or protocol parameters before retrying. |
| 401 | Retire unusable authority and require sign-in or fresh authorization. |
| 403 | Surface the authority, scope, origin or safety refusal; obtain deliberately approved authority where appropriate. |
| 404 | Stop displaying the missing resource; do not infer that anonymous access would be allowed. |
| 409 | Revalidate session/resource state; reconcile the conflict before a deliberate retry. |
| 410 | Stop publishing deleted content. |
| 429 | Clear unavailable protected views and back off. Anonymous limits return `Retry-After` seconds; do not assume every limiter response carries it. |
| 503 | Suppress protected views while validation is unavailable; retry later with bounded backoff. |

Never retry a protected refusal anonymously. Never automatically retry a write with a fresh intent after an uncertain result. Preserve the original intent for an explicit same-request retry; see [mutation retries](/lifecycle-and-safety#safe-mutation-retries).

## Complete public error catalog

The catalog includes domain refusals, lifecycle/recovery admission refusals and OAuth/provider protocol errors. A code's meaning does not make every code possible on every endpoint; use that operation's reference for its status and shape.

| Code | Meaning and action |
| - | - |
| `unknown_or_immutable_field` | Remove unknown fields; immutable fields cannot be changed. |
| `invalid_text` | Supply nonblank post text of at most 5000 Unicode code points. |
| `invalid_json` | Supply a JSON object. |
| `intent_required` | Supply an intentId matching the documented pattern. |
| `unsupported_audience` | Only public posts are supported. |
| `invalid_parent` | Supply a string parentId. |
| `revision_required` | Supply the current integer revision. |
| `self_relation` | An actor cannot follow or like itself through this relation. |
| `self_block` | An actor cannot block itself. |
| `invalid_report` | Check target, nonblank reason, and evidence size. |
| `invalid_cursor` | Use a nonnegative safe integer after cursor. |
| `authentication_required` | Obtain a valid bearer credential; never fall back to anonymous inside a signed-in experience. |
| `auth_unavailable` | Authentication failed or is unavailable; retire or revalidate the session. |
| `authority_unavailable` | The grant/account/application is no longer usable; revalidate and retire stale authority. |
| `capability_required` | Request the required scope in a new authorization grant. |
| `not_owner` | Only the author can edit or delete this post. |
| `interaction_unavailable` | The interaction is unavailable under current safety rules. |
| `social_authority_required` | Use social bearer authority. |
| `not_found` | The addressed resource or route does not exist. |
| `intent_conflict` | An intentId was reused for a different request; choose a fresh intent for a new action. |
| `revision_conflict` | Refresh the post and apply the edit against its current revision. |
| `post_deleted` | The post has been deleted; stop publishing its body. |
| `post_unavailable` | The post is unavailable under current network rules. |
| `parent_unavailable` | The reply parent is unavailable. |
| `effect_mismatch` | The conditional mutation was not accepted; revalidate before retrying. |
| `domain_plan_too_large` | Reduce the mutation size. |
| `publishing_paused` | Publishing is temporarily paused by the operator. |
| `pilot_rate_limited` | Back off; anonymous admission supplies Retry-After seconds. |
| `protected_read_unavailable` | Protected read admission failed; do not serve cached content. |
| `protected_read_storage_unavailable` | Protected-read storage is unavailable. |
| `recovery_unavailable` | Recovery authority is unavailable. |
| `domain_storage_unavailable` | Domain storage is unavailable. |
| `pilot_storage_unavailable` | Pilot storage is unavailable. |
| `pilot_limits_unavailable` | Limit storage is unavailable; admission fails closed. |
| `trusted_address_unavailable` | Trusted connecting-address admission is unavailable. |
| `origin_required` | Supply the exact network Origin where required. |
| `origin_mismatch` | The URL or supplied Origin does not match the configured network origin. |
| `restriction_witness_required` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `restriction_witness_unavailable_or_incomplete` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `recovery_state_missing` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `recovery_publication_changed` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `recovery_quarantined` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `lifecycle_revision_conflict` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `witness_prepare_mismatch` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `ambiguous_acceptance_requires_independent_proof` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `witness_acceptance_mismatch` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `witness_finalize_unconfirmed` | Current lifecycle/recovery proof is unavailable; stop protected publication and retry only after authority revalidation. |
| `invalid_request` | OAuth protocol refusal: invalid request. Validate the request/client/grant and restart authorization for invalid credentials. |
| `invalid_client` | OAuth protocol refusal: invalid client. Validate the request/client/grant and restart authorization for invalid credentials. |
| `invalid_grant` | OAuth protocol refusal: invalid grant. Validate the request/client/grant and restart authorization for invalid credentials. |
| `invalid_scope` | OAuth protocol refusal: invalid scope. Validate the request/client/grant and restart authorization for invalid credentials. |
| `unsupported_grant_type` | OAuth protocol refusal: unsupported grant type. Validate the request/client/grant and restart authorization for invalid credentials. |
| `unsupported_response_type` | OAuth protocol refusal: unsupported response type. Validate the request/client/grant and restart authorization for invalid credentials. |
| `access_denied` | OAuth protocol refusal: access denied. Validate the request/client/grant and restart authorization for invalid credentials. |
| `temporarily_unavailable` | OAuth protocol refusal: temporarily unavailable. Validate the request/client/grant and restart authorization for invalid credentials. |
| `server_error` | OAuth protocol refusal: server error. Validate the request/client/grant and restart authorization for invalid credentials. |
| `invalid_token` | OAuth protocol refusal: invalid token. Validate the request/client/grant and restart authorization for invalid credentials. |
| `unsupported_token_type` | OAuth protocol refusal: unsupported token type. Validate the request/client/grant and restart authorization for invalid credentials. |
| `invalid_target` | OAuth protocol refusal: invalid target. Validate the request/client/grant and restart authorization for invalid credentials. |
| `invalid_signature` | The signed authorization transaction was rejected; restart browser authorization. |
| `invalid_redirect_uri` | Use an exact registered redirect URI. |
| `invalid_request_uri` | This request URI is invalid; use the supported direct authorization request. |
| `request_not_supported` | Request objects are unsupported in this pilot profile. |
| `request_uri_not_supported` | Request URI transport is unsupported in this pilot profile. |
| `login_required` | An account login is required before authorization can proceed. |
| `interaction_required` | Complete the required browser interaction. |
| `account_selection_required` | Select an account before continuing authorization. |
| `consent_required` | The user must deliberately consent to the requested scopes. |
| `UNAUTHORIZED` | The maintained provider requires an authenticated account session. |
| `VALIDATION_ERROR` | The maintained provider rejected the request shape. |
| `TOO_MANY_REQUESTS` | The maintained provider rate limit was exhausted; back off. |
| `FORBIDDEN` | The maintained provider refused authority for this operation. |
| `BAD_REQUEST` | The maintained provider rejected the request. |
| `INTERNAL_SERVER_ERROR` | The maintained provider could not complete the operation; retry after recovery. |
| `NOT_FOUND` | The maintained provider resource was not found. |
| `METHOD_NOT_ALLOWED` | The maintained provider does not support this method. |
| `UNSUPPORTED_MEDIA_TYPE` | Use the documented request Content-Type. |

For `invalid_client`, check server-side credentials and client authentication; ask the operator to repair registration if needed. For `invalid_grant` or `invalid_token`, discard unusable delegated authority and restart authorization, rather than reusing a consumed code or rotated refresh token. For `invalid_scope`, correct the requested set and obtain registration approval/consent as needed. For `access_denied`, respect the user's decision. For `temporarily_unavailable` and `server_error`, back off; do not loop through browser authorization. For login, account-selection, interaction or consent requirements, let the user complete the indicated provider browser step.

Storage, witness and recovery failures are fail-closed. Do not serve a cached protected body while they persist. Diagnostic descriptions can change and must not become UI identifiers or be logged together with credentials, callback URLs or cookie values.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.