ENS Ads API HTTP Response Codes & Error JSON Formats

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 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:

{
  "status": "success",
  ...
}

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

{
  "status": "success",
  "data": [ ... ],
  "count": 1
}

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

{
  "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.

{
  "status": "error",
  "message": "placement parameter is required"
}

401 — Unauthorized

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

{
  "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 for recommended strategies.

{
  "status": "error",
  "message": "Rate limit exceeded"
}

​Status codes

​Success response format

​Error response format

​400 — Bad Request

​401 — Unauthorized

​429 — Too Many Requests