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

# Errors

> Status codes, the error envelope, and how billing behaves on failure.

## Error envelope

Errors use the same envelope as success, with `status: false` and a human
message in `error`:

```json theme={null}
{
  "status": false,
  "data": null,
  "error": "Missing required field: text"
}
```

The HTTP status code carries the machine‑readable meaning.

## Status codes

| Code  | Meaning                 | Typical cause                                                                                                            |
| ----- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| `200` | Success                 | The call ran and returned data.                                                                                          |
| `400` | Bad request             | A required field is missing or malformed.                                                                                |
| `401` | Unauthorized            | Missing/invalid API key, or an invalid X `auth_token`.                                                                   |
| `402` | Payment required        | Your credit balance is too low for this call.                                                                            |
| `403` | Forbidden               | The X account isn't allowed to do this (e.g. deleting another user's tweet, or publishing an article without X Premium). |
| `404` | Not found               | The user, tweet or article doesn't exist.                                                                                |
| `409` | Conflict                | Duplicate action (e.g. posting an identical tweet).                                                                      |
| `429` | Rate limited            | X's daily action limit was hit.                                                                                          |
| `502` | Upstream error          | X returned an unexpected response.                                                                                       |
| `503` | Temporarily unavailable | X asked us to retry later.                                                                                               |

## Billing on failure

You are **never** charged for our errors, auth failures, rate limits, or upstream
problems (`401`, `402`, `429`, `5xx`). A successful call (`200`) is charged
\$0.001. Genuine "not found" lookups are **not** charged.

## Idempotent actions

Several write endpoints are idempotent — calling them when the action is already
done returns `200` success rather than an error:

* **Like / Unlike**, **Retweet / Unretweet**, **Bookmark / Unbookmark** — repeating succeeds.
* **Delete Tweet** — deleting an already‑deleted tweet returns `deleted: true, already: true`.
* **Follow / Unfollow** — repeating reflects the current state.

## Common X error mappings

Some X‑specific conditions map to friendly statuses:

| Condition                              | Our status         |
| -------------------------------------- | ------------------ |
| Duplicate tweet                        | `409`              |
| Reply restricted by author             | `403`              |
| Not a member of the community          | `403`              |
| Over daily action limit                | `429`              |
| Deleting another user's tweet          | `403`              |
| Already liked / bookmarked / retweeted | `200` (idempotent) |