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

# Errors

> HTTP status codes and the client error envelope.

Product API errors return a JSON body:

```json theme={null}
{
  "error": "Human-readable message",
  "code": "MACHINE_CODE"
}
```

`code` is present for domain errors. Generic HTTP errors may omit it.

## Status codes

| Status | Meaning                                        |
| ------ | ---------------------------------------------- |
| `400`  | Invalid request (validation, disabled market)  |
| `401`  | Missing or invalid API key                     |
| `402`  | Insufficient credits                           |
| `404`  | Resource not found                             |
| `409`  | Conflict (e.g. duplicate active watch)         |
| `500`  | Internal server error                          |
| `503`  | Upstream or parse failure — retry with backoff |

## Domain codes

| `code`                               | Typical status | Client message               |
| ------------------------------------ | -------------- | ---------------------------- |
| `VALIDATION`                         | 400            | Invalid request              |
| `NOT_FOUND`                          | 404            | Item not found               |
| `CONFLICT`                           | 409            | Request conflict             |
| `INSUFFICIENT_CREDITS`               | 402            | Insufficient credits         |
| `UNAVAILABLE`, `PARSE`, `NETWORK`, … | 503            | Item temporarily unavailable |

## X availability

X endpoints can return definitive content-state outcomes. These are safe to expose to end users — they are not platform or session errors.

### Tweet lookup (partial success)

`GET /v1/x/tweets` and `POST /v1/x/tweets/lookup` return HTTP **200** with a partial-success envelope:

```json theme={null}
{
  "meta": { "requested": 2, "found": 1 },
  "data": [ { "...": "tweet" } ],
  "errors": [ { "id": "123", "code": "TWEET_NOT_FOUND" } ]
}
```

Per-ID availability codes:

| `code`            | Meaning                                |
| ----------------- | -------------------------------------- |
| `TWEET_NOT_FOUND` | Tweet does not exist or is unavailable |
| `TWEET_PROTECTED` | Tweet is from a protected account      |
| `USER_SUSPENDED`  | Author account is suspended            |

Credits are charged per the [tweet lookup rate](/credits#x) (1 base + 1 per found tweet).

### XUser routes (soft 404)

Profile and XUser-keyed endpoints (`/v1/x/users/:ref`, timelines, followers, etc.) return HTTP **404** with:

| `code`           | Meaning                   |
| ---------------- | ------------------------- |
| `USER_NOT_FOUND` | User does not exist       |
| `USER_PROTECTED` | User account is protected |
| `USER_SUSPENDED` | User account is suspended |

Credits are still charged for definitive 404s — Nephia resolved the profile state.

<Note>
  Every response includes `X-Request-Id` for support correlation.
</Note>