Error Handling

The Audian API uses standard HTTP status codes and returns detailed error information to help you diagnose and resolve issues.

Error Response Format

When an error occurs, the API returns a JSON response:

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": {
    "message": "invalid credentials"
  },
  "error": "401",
  "message": "unauthorized",
  "request_id": "req_xyz789",
  "status": "error"
}

Error Response Fields

Field	Description
status	Always "error" for error responses
error	HTTP status code as string
message	Error type/category
data.message	Human-readable error description
request_id	Unique identifier for the request

HTTP Status Codes

Code	Meaning	Description
200	Success	Request completed successfully
201	Created	Resource created successfully
204	No Content	Successful delete operation
400	Bad Request	Invalid request parameters
401	Unauthorized	Invalid or missing auth token
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Server Error	Internal server error

Common Error Scenarios

Authentication Errors (401)

{
  "data": {
    "message": "invalid credentials"
  },
  "error": "401",
  "message": "unauthorized",
  "status": "error"
}

Causes:

• Invalid or expired auth token
• Missing X-Auth-Token header
• Invalid API key during authentication

Resolution:

1. Verify your API key is correct
2. Re-authenticate to get a fresh auth token
3. Ensure the X-Auth-Token header is included

Bad Request Errors (400)

{
  "data": {
    "message": "field required: email"
  },
  "error": "400",
  "message": "bad_request",
  "status": "error"
}

Causes:

• Missing required field
• Invalid field format
• Invalid JSON in request body

Resolution:

1. Check required fields in the documentation
2. Verify data types match expected format
3. Ensure request body is valid JSON wrapped in {"data": {...}}

Not Found Errors (404)

{
  "data": {
    "message": "resource not found"
  },
  "error": "404",
  "message": "not_found",
  "status": "error"
}

Causes:

• Resource ID doesn't exist
• Resource was deleted
• Wrong account ID in URL

Resolution:

1. Verify the resource ID is correct
2. Check the resource hasn't been deleted
3. Ensure you're using the correct account ID

Rate Limit Errors (429)

{
  "data": {
    "message": "rate limit exceeded"
  },
  "error": "429",
  "message": "too_many_requests",
  "status": "error"
}

Causes:

• Too many requests in a short period
• Token bucket exhausted

Resolution:

1. Implement exponential backoff
2. Cache results where possible
3. Use webhooks instead of polling

Error Handling in Code

Python

import requests

def make_api_request(url, headers):
    response = requests.get(url, headers=headers)
    data = response.json()

    if data.get('status') == 'error':
        error_code = data.get('error')
        message = data.get('data', {}).get('message', 'Unknown error')

        if error_code == '401':
            raise AuthenticationError(message)
        elif error_code == '404':
            raise NotFoundError(message)
        elif error_code == '429':
            raise RateLimitError(message)
        else:
            raise APIError(f"{error_code}: {message}")

    return data['data']

JavaScript

async function makeApiRequest(url, headers) {
  const response = await fetch(url, { headers });
  const data = await response.json();

  if (data.status === 'error') {
    const errorCode = data.error;
    const message = data.data?.message || 'Unknown error';

    switch (errorCode) {
      case '401':
        throw new AuthenticationError(message);
      case '404':
        throw new NotFoundError(message);
      case '429':
        throw new RateLimitError(message);
      default:
        throw new APIError(`${errorCode}: ${message}`);
    }
  }

  return data.data;
}

Retry Logic

Implement retry with exponential backoff for transient errors:

import time

def retry_with_backoff(func, max_retries=3, initial_delay=1):
    for attempt in range(max_retries):
        try:
            return func()
        except RateLimitError:
            if attempt == max_retries - 1:
                raise
            delay = initial_delay * (2 ** attempt)
            print(f"Rate limited, waiting {delay}s...")
            time.sleep(delay)
        except ServerError:
            if attempt == max_retries - 1:
                raise
            delay = initial_delay * (2 ** attempt)
            time.sleep(delay)

Debugging Tips

1. Check the request_id: Include this when contacting support
2. Verify JSON format: Request body must be {"data": {...}}
3. Check auth token: Tokens expire - re-authenticate if needed
4. Review account_id: Ensure it matches your authenticated account
5. Enable logging: Log request/response for debugging

Topics

• HTTP Status Codes - Detailed status code reference
• Error Codes - Complete error code list
• Troubleshooting - Common issues and solutions