Skip to main content
Every error response from the ENS Ads API follows a consistent structure with two fields: status, which is always "error" for failed requests, and message, which describes what went wrong. Building your integration to check for these fields before attempting to use the response data will make your implementation resilient to transient failures, misconfiguration, and rate limits.
Always check the response status before attempting to render campaigns or record tracking events. Rendering a failed or empty response as though it were valid data can result in broken UI states or inaccurate performance reporting.

​
HTTP status code overview

Status codeNameMeaning
200OKRequest succeeded. Use the response data.
400Bad RequestA required parameter is missing or invalid.
401UnauthorizedYour API key is missing or incorrect.
404Not FoundThe requested resource does not exist.
429Too Many RequestsYou have exceeded the rate limit.
500Internal Server ErrorA server-side error occurred. Retry later.

​
Error responses

​
400 — missing required parameter

You will receive a 400 when a required query parameter is absent. The most common cause is omitting placement from a GET /campaigns/fetch request. 
{
  "status": "error",
  "message": "placement parameter is required"
}
Check that all required parameters are present before making the request. For GET /campaigns/fetch, placement is the only required query parameter.

​
401 — unauthorized

A 401 means the API key in your Authorization header is missing, malformed, or does not match a valid key. 
{
  "status": "error",
  "message": "unauthorized"
}
Confirm that your request includes the header Authorization: Bearer YOUR_API_KEY and that the key value is correct. API keys must never be included in client-side code.

​
404 — not found

A 404 is returned when the resource you are trying to reach does not exist. This can occur if a campaignId passed to the impression or click endpoints no longer corresponds to an active campaign.

​
429 — rate limit exceeded

A 429 means your integration is making requests faster than the API allows. 
{
  "status": "error",
  "message": "Rate limit exceeded"
}
Implement exponential backoff when you receive a 429. Wait before retrying and reduce request frequency if you hit this error repeatedly.

​
500 — internal server error

A 500 indicates a server-side problem. These are typically transient. Log the error and retry the request after a short delay. If the problem persists, contact ENS Ads support.

​
Error handling patterns

The examples below show how to catch and respond to API errors in both JavaScript and Python. 
const BASE_URL = 'https://ads.enslive.live/api/v1';
const API_KEY = 'YOUR_API_KEY';

async function fetchCampaigns(placement, location, device) {
  try {
    const response = await fetch(
      `${BASE_URL}/campaigns/fetch?placement=${placement}&location=${location}&device=${device}`,
      {
        headers: {
          'Authorization': `Bearer ${API_KEY}`
        }
      }
    );

    if (!response.ok) {
      const error = await response.json();
      console.error(`API error ${response.status}:`, error.message);

      if (response.status === 401) {
        // Stop execution — API key problem requires manual fix
        throw new Error('Invalid API key. Check your Authorization header.');
      }

      if (response.status === 429) {
        // Back off and retry
        console.warn('Rate limit hit. Retrying after delay...');
      }

      return [];
    }

    const data = await response.json();
    return data.data;
  } catch (error) {
    console.error('Failed to fetch campaigns:', error);
    return [];
  }
}