# Errors

> Page: https://docs.flung.dev/reference/api/errors. Index of every page: https://docs.flung.dev/llms.txt

Every failed call answers with the same JSON shape and a stable code. Branch on the code; the message is for people and may change.

## TL;DR

| Question | Answer |
|---|---|
| What does a failure look like? | `{ "error": { "code": "...", "message": "...", "details": ... } }` with a 4xx or 5xx status. |
| What should my code branch on? | `error.code`. It never changes for a given problem. |
| What does the SDK do? | It throws `FlungError` with `status`, `code`, `message` and `details`. Two codes are its own: `network_error` (no answer arrived) and `unexpected_response`. |
| Which are worth retrying? | `rate_limited` after `Retry-After`, and `internal_error` with the same idempotency key. The SDK retries these and network failures by itself. |

## Codes

22 codes.

| Code | What to do |
|---|---|
| `unauthorized` | The credential is missing, unknown, revoked or expired. Check the key, or refresh the OAuth token. |
| `forbidden` | The credential cannot do this: a connect token outside its seven calls or its page, or a key without the scope. |
| `validation_failed` | The request does not match the schema. `details` lists each problem with its path. |
| `not_found` | No such resource in this workspace, or the route does not exist. |
| `unknown_accounts` | One or more `accountIds` are not this workspace's. `details.accountIds` names them. |
| `platform_not_supported` | Flung cannot connect that platform here. |
| `media_required` | The platform refuses a post with no image or video. |
| `account_needs_reconnect` | The account's access ended. Start a reconnect and have the person approve it. |
| `not_configured` | The platform's app credentials are not set up in this environment. |
| `connect_failed` | The platform refused to start the connect. The message says why. |
| `platform_error` | The platform answered with an error. The message carries its reason. |
| `post_not_editable` | The post has started publishing or has finished, so it can no longer change. |
| `unknown_variable` | The text names a `{{variable}}` the workspace has not set. |
| `rate_limited` | Too many requests. Wait for the seconds in `Retry-After`. |
| `unsupported_media` | The file is not a type Flung accepts, judged from its first bytes. |
| `media_too_large` | The file is over the limit for its type. |
| `unknown_media` | One or more `mediaIds` are not this workspace's. |
| `media_not_ready` | A file is still uploading. Wait until its status is `ready`. |
| `text_too_long` | The text is over a platform's limit. `details` names the platform and the limit. |
| `publish_at_in_past` | `publishAt` is in the past. Omit it to publish now. |
| `idempotency_key_reused` | The `Idempotency-Key` was used before with a different request. Use a new key for new work. |
| `internal_error` | Something failed on Flung's side. Retry with the same idempotency key. |