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

# ENS Ads API HTTP Response Codes & Error JSON Formats

> ENS Ads responses use a JSON envelope with a status field. Reference codes 200, 400, 401, 404, 429, and 500 with success and error payload examples.

Every response from the ENS Ads API uses a standard JSON envelope. Successful responses always include a `"status": "success"` field alongside the relevant data. Error responses always include `"status": "error"` and a `message` field describing the problem. Inspect the HTTP status code first, then read the `message` field for details when handling errors in your integration.

## Status codes

| Code  | Status                | Description                                                                                                                          |
| ----- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `200` | OK                    | The request was successful. The response body contains the requested data or a confirmation message.                                 |
| `400` | Bad Request           | The request is missing a required parameter or contains an invalid value. Check the `message` field for specifics.                   |
| `401` | Unauthorized          | The `Authorization` header is missing or the API key is invalid. Verify your credentials and that the header is formatted correctly. |
| `404` | Not Found             | The requested resource does not exist. Verify the endpoint path and any IDs in your request.                                         |
| `429` | Too Many Requests     | You have exceeded the API rate limit. Back off and retry after a short delay. See [Rate Limits](/api/rate-limits) for guidance.      |
| `500` | Internal Server Error | An unexpected error occurred on the server. If this persists, contact ENS Ads support.                                               |

## Success response format

All successful responses follow this envelope structure:

```json theme={null}
{
  "status": "success",
  ...
}
```

For the Fetch Campaigns endpoint, the envelope includes a `data` array and a `count`:

```json theme={null}
{
  "status": "success",
  "data": [ ... ],
  "count": 1
}
```

For tracking endpoints (impression and click), the envelope includes a `message` confirmation:

```json theme={null}
{
  "status": "success",
  "message": "Impression tracked successfully"
}
```

## Error response format

All error responses include `"status": "error"` and a `message` field. The `message` value provides a human-readable description of what went wrong.

### 400 — Bad Request

Returned when a required parameter is absent or a value fails validation.

```json theme={null}
{
  "status": "error",
  "message": "placement parameter is required"
}
```

### 401 — Unauthorized

Returned when the `Authorization` header is missing or the supplied API key is not recognized.

```json theme={null}
{
  "status": "error",
  "message": "unauthorized"
}
```

### 429 — Too Many Requests

Returned when your integration exceeds the allowed request rate. Implement exponential backoff and retry logic to handle this gracefully. See [Rate Limits](/api/rate-limits) for recommended strategies.

```json theme={null}
{
  "status": "error",
  "message": "Rate limit exceeded"
}
```