> ## 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 |
| `403` | Account banned or closed |
| `404` | Resource not found |
| `409` | Conflict (e.g. a plan limit reached, or a bucket name that already exists) |
| `422` | Idempotency key reused with a different body |
| `429` | Request quota exceeded — see [Limits](/limits) |
| `500` | Internal server error |
| `503` | Temporary Source or platform failure — retry with backoff |

## Idempotent retries

Every `POST` accepts an optional `Idempotency-Key` header (any unique string ≤255 chars, e.g. a UUID). Retrying with the same key within 24 hours replays the original response (with an `Idempotency-Replayed: true` header) instead of re-executing, so a network failure mid-request can never create a duplicate keyword or double-charge credits. Reusing a key with a different body returns `422` (`IDEMPOTENCY_KEY_REUSED`); a concurrent duplicate returns `409` (`IDEMPOTENCY_CONFLICT`). Responses with status `401`, `429`, or `5xx` are never stored, so those retries re-execute. The [Node SDK](/sdk) sends a generated key on every POST automatically.

## Domain codes

| `code` | Typical status | Client message |
| - | - | - |
| `VALIDATION` | 400 | Invalid request |
| `UNAUTHORIZED` | 401 | Unauthorized |
| `INSUFFICIENT_CREDITS` | 402 | Insufficient credits |
| `ACCOUNT_BANNED` | 403 | Account is banned |
| `ACCOUNT_CLOSED` | 403 | Account is closed |
| `NOT_FOUND` | 404 | Item not found |
| `CONFLICT` | 409 | Request conflict |
| `TOO_MANY_REQUESTS` | 429 | Rate limit exceeded |
| `MAINTENANCE` | 503 | Service under maintenance |
| `CONCURRENCY_EXHAUSTED` | 503 | Service temporarily unavailable |
| `UNAVAILABLE`, `PARSE`, `NETWORK`, `RATE_LIMITED`, … | 503 | Item temporarily unavailable |

## Rate limits

`/v1/*` is quota-limited per Account per minute, and the ceiling depends on your plan —
see [Limits](/limits). Over the quota you get **429** with `code: "TOO_MANY_REQUESTS"`:

```json theme={null}
{
  "error": "Rate limit exceeded",
  "code": "TOO_MANY_REQUESTS"
}
```

Every response carries IETF draft-7 `RateLimit` and `RateLimit-Policy` headers so you can
pace yourself before being throttled; a 429 also carries `Retry-After` in seconds. The
[Node SDK](/sdk) retries 429 automatically and honours `Retry-After`.

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


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