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

# Errors

> The error envelope and what each code means.

Every 4xx and 5xx response uses the same envelope:

```json theme={null}
{
  "error": {
    "code": "BAD_REQUEST",
    "message": "Media 1: video must be at most 60 seconds for STORIES",
    "details": {}
  }
}
```

`code` is machine-readable and stable. `message` is written for a human and may
change. `details` carries field-level validation errors when there are any.

## Codes

| HTTP | `code`                  | Means                                                           |
| ---- | ----------------------- | --------------------------------------------------------------- |
| 400  | `BAD_REQUEST`           | The request was malformed, or media failed platform validation. |
| 401  | `UNAUTHORIZED`          | Missing, malformed, or expired credential.                      |
| 402  | `PAYMENT_REQUIRED`      | The workspace's plan does not cover this call.                  |
| 403  | `FORBIDDEN`             | Authenticated, but not permitted on this project.               |
| 404  | `NOT_FOUND`             | No such resource, or not visible to this credential.            |
| 409  | `CONFLICT`              | The resource changed underneath you.                            |
| 412  | `PRECONDITION_FAILED`   | A required precondition was not met.                            |
| 413  | `PAYLOAD_TOO_LARGE`     | The body exceeded the endpoint's size limit.                    |
| 422  | `UNPROCESSABLE_CONTENT` | Well-formed, but semantically rejected.                         |
| 429  | `TOO_MANY_REQUESTS`     | Rate limited — back off and retry.                              |
| 500  | `INTERNAL_SERVER_ERROR` | An unexpected failure on our side.                              |
| 502  | `BAD_GATEWAY`           | An upstream platform (Meta, TikTok, Google) failed.             |
| 503  | `SERVICE_UNAVAILABLE`   | Temporarily unavailable.                                        |
| 504  | `GATEWAY_TIMEOUT`       | An upstream platform timed out.                                 |

## Upstream platform failures

Publishing talks to Meta, TikTok, YouTube and Google. When one of those rejects
a post, the failure surfaces two ways depending on when it happens:

* **Synchronously** — the publish call returns `502 BAD_GATEWAY` with the
  platform's reason in `message`.
* **Asynchronously** — a scheduled post moves to `status: "failed"` with the
  reason in `errorMessage`. Poll
  [Get post status](/api-reference/socials/get-post-status), and retry by
  calling [Publish post immediately](/api-reference/socials/publish-post-immediately).

<Warning>
  Retrying a `failed` post re-runs delivery. Retrying a post that actually
  succeeded upstream but failed to record can double-post. Check `permalink` on
  the post before retrying.
</Warning>