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

# Errors

> Standard error shape and HTTP status codes across all Seyaha APIs.

All error responses share the same JSON envelope:

```json theme={null}
{
  "success": 0,
  "error": ["field: reason", "another: issue"],
  "message": "Human-readable summary",
  "code": 400
}
```

| Field     | Type       | Description                                       |
| --------- | ---------- | ------------------------------------------------- |
| `success` | `0`        | Always `0` for errors                             |
| `error`   | `string[]` | Machine-readable list of individual error details |
| `message` | `string`   | Short human-readable description                  |
| `code`    | `number`   | HTTP status code, mirrored in the body            |

## HTTP status codes

| Code  | Meaning               | Common causes                                                          |
| ----- | --------------------- | ---------------------------------------------------------------------- |
| `400` | Bad Request           | Failed Zod validation, missing required field, business rule violation |
| `401` | Unauthorized          | Missing, expired, or invalid credential                                |
| `403` | Forbidden             | Authenticated but wrong role (e.g. non-admin hitting admin route)      |
| `404` | Not Found             | Resource ID doesn't exist or doesn't belong to the caller              |
| `429` | Too Many Requests     | Rate limit exceeded — back off and retry                               |
| `500` | Internal Server Error | Unexpected server-side failure                                         |

## Validation errors (400)

Validation uses [Zod](https://zod.dev). Each failed field is a separate entry in the
`error` array using the format `fieldPath: message`:

```json theme={null}
{
  "success": 0,
  "error": [
    "base_url: Invalid url",
    "auth_type: Invalid enum value. Expected 'bearer' | 'api_key'"
  ],
  "message": "Validation Error",
  "code": 400
}
```

## Rate limiting (429)

Affiliate and Reseller endpoints are rate-limited per API token / JWT.

```json theme={null}
{
  "success": 0,
  "error": ["rate limit exceeded"],
  "message": "rate limit exceeded",
  "code": 429
}
```

When you hit a 429, inspect the `Retry-After` response header (if present) and wait
that many seconds before retrying.