Errors & Status Codes - ElasticFunnels.io Documentation

Error Response Format

Most failed requests return a JSON body. The most common validation/auth shape is:

{
  "message": "Error message describing what went wrong",
  "errors": {
    "field_name": [
      "Specific validation error for this field"
    ]
  }
}

Alternate shapes (also used in production)

Endpoints are not fully normalized to one schema. Also handle these when present:

Pattern	Typical status	Example
`message` only	401, 404	`{ "message": "Invalid API key or brand access denied" }`
`error` string	403, 404, 409	`{ "error": "component_in_use", "message": "...", "usage_count": 3 }`
`success: false`	409	`{ "success": false, "message": "...", "code": "revision_conflict" }`
`plan_error`	403, 422	`{ "error": "Upgrade required...", "plan_error": { ... } }`
Laravel `errors` only	422	`{ "errors": { "domain": ["The domain has already been taken."] } }`
Non-JSON / HTML	302, 500	Session redirect to login, or proxy error pages — check `Content-Type`

Always branch on HTTP status code first, then parse JSON if Content-Type includes application/json. Log the raw response body when debugging unknown failures.

HTTP Status Codes

ElasticFunnels uses conventional HTTP response codes to indicate the success or failure of an API request.

Success Codes

The request was successful.

Created

The resource was successfully created.

No Content

The request was successful but there’s no content to return (typically for DELETE requests).

Client Error Codes

Bad Request

The request was malformed or contains invalid parameters.

Unauthorized

Authentication failed. Check your API key.

Forbidden

You don’t have permission to access this resource.

Not Found

The requested resource doesn’t exist.

Unprocessable Entity

Validation failed. Check the errors field in the response.

Too Many Requests

Rate limit exceeded. Slow down your requests.

Server Error Codes

Internal Server Error

Something went wrong on our end. Please contact support if this persists.

Service Unavailable

The service is temporarily unavailable. Please try again later.

Common Error Scenarios

Authentication Errors

Invalid API Key

{
  "message": "Invalid API key"
}

Status Code: 401 Solution: Check that your API key is correct and hasn’t been regenerated.

No Brand Access

{
  "message": "Invalid API key or brand access denied"
}

Status Code: 401 Solution: Ensure your API key has access to the specified brand/project.

Validation Errors

Missing Required Fields

{
  "message": "The given data was invalid.",
  "errors": {
    "name": [
      "The name field is required."
    ],
    "price": [
      "The price field is required."
    ]
  }
}

Status Code: 422 Solution: Include all required fields in your request.

Invalid Field Values

{
  "message": "The given data was invalid.",
  "errors": {
    "price": [
      "The price must be a number.",
      "The price must be at least 0."
    ],
    "status": [
      "The selected status is invalid."
    ]
  }
}

Status Code: 422 Solution: Ensure field values meet the requirements (correct type, valid options, etc.).

Permission Errors

Insufficient Permissions

{
  "message": "You don't have permission to perform this action."
}

Status Code: 403 Solution: This action requires higher permissions (e.g., Admin or Owner role).

Resource Errors

Resource Not Found

{
  "message": "Resource not found"
}

Status Code: 404 Solution: Check that the resource ID is correct and the resource exists.

Rate Limiting

Too Many Requests

{
  "message": "Too many requests. Please slow down."
}

Status Code: 429 Solution: Implement exponential backoff or reduce request frequency.

Best Practices for Error Handling

Check Status Codes

Always check the HTTP status code before parsing the response

Handle Validation Errors

Display validation errors to users in a friendly format

Implement Retry Logic

Retry failed requests with exponential backoff for 5xx errors

Log Errors

Log error responses for debugging and monitoring

Example Error Handling

Here are examples of proper error handling in different languages:

JavaScript

try {
  const response = await fetch(
    'https://app.elasticfunnels.io/api/brands/123/pages',
    {
      method: 'POST',
      headers: {
        'EF-Access-Key': 'your_api_key_here',
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({ name: 'New Page' })
    }
  );

  if (!response.ok) {
    const error = await response.json();
    
    if (response.status === 401) {
      console.error('Authentication failed:', error.message);
    } else if (response.status === 422) {
      console.error('Validation errors:', error.errors);
    } else {
      console.error('API error:', error.message);
    }
    
    throw new Error(error.message);
  }

  const data = await response.json();
  console.log('Success:', data);
} catch (error) {
  console.error('Request failed:', error);
}

Python

import requests

try:
    response = requests.post(
        'https://app.elasticfunnels.io/api/brands/123/pages',
        headers={
            'EF-Access-Key': 'your_api_key_here',
            'Content-Type': 'application/json'
        },
        json={'name': 'New Page'}
    )
    
    response.raise_for_status()
    data = response.json()
    print('Success:', data)
    
except requests.exceptions.HTTPError as e:
    error_data = e.response.json()
    
    if e.response.status_code == 401:
        print('Authentication failed:', error_data['message'])
    elif e.response.status_code == 422:
        print('Validation errors:', error_data['errors'])
    else:
        print('API error:', error_data['message'])
        
except requests.exceptions.RequestException as e:
    print('Request failed:', str(e))

PHP

<?php

$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, 'https://app.elasticfunnels.io/api/brands/123/pages');
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'EF-Access-Key: your_api_key_here',
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode(['name' => 'New Page']));

$response = curl_exec($ch);
$statusCode = curl_getinfo($ch, CURLINFO_HTTP_CODE);
curl_close($ch);

$data = json_decode($response, true);

if ($statusCode >= 200 && $statusCode < 300) {
    echo 'Success: ' . print_r($data, true);
} else {
    if ($statusCode === 401) {
        echo 'Authentication failed: ' . $data['message'];
    } elseif ($statusCode === 422) {
        echo 'Validation errors: ' . print_r($data['errors'], true);
    } else {
        echo 'API error: ' . $data['message'];
    }
}

Need Help?

If you encounter persistent errors or need assistance:

Contact Support

support@elasticfunnels.io

​Error Response Format

​Alternate shapes (also used in production)

​HTTP Status Codes

​Success Codes

​Client Error Codes

​Server Error Codes

​Common Error Scenarios

​Authentication Errors

​Invalid API Key

​No Brand Access

​Validation Errors

​Missing Required Fields

​Invalid Field Values

​Permission Errors

​Insufficient Permissions

​Resource Errors

​Resource Not Found

​Rate Limiting

​Too Many Requests

​Best Practices for Error Handling

Check Status Codes

Handle Validation Errors

Implement Retry Logic

Log Errors

​Example Error Handling

​JavaScript

​Python

​PHP

​Need Help?

Contact Support

Error Response Format

Alternate shapes (also used in production)

HTTP Status Codes

Success Codes

Client Error Codes

Server Error Codes

Common Error Scenarios

Authentication Errors

Invalid API Key

No Brand Access

Validation Errors

Missing Required Fields

Invalid Field Values

Permission Errors

Insufficient Permissions

Resource Errors

Resource Not Found

Rate Limiting

Too Many Requests

Best Practices for Error Handling

Example Error Handling

JavaScript

Python

PHP

Need Help?