Skip to main content

Response Format

This guide explains how the Audian API structures and returns responses.

Response Structure​

All API responses follow a consistent format:

{
  "auth_token": "{AUTH_TOKEN}",
  "data": { /* Resource data */ },
  "request_id": "{REQUEST_ID}",
  "status": "success"
}

Response Components​

  • auth_token: Your authentication token (returned for convenience)
  • data: The actual response content (varies by endpoint)
  • request_id: Unique identifier for this request (useful for debugging)
  • status: "success" or "error"

Successful Responses​

Single Resource​

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": {
    "id": "user_abc123",
    "username": "jsmith",
    "first_name": "John",
    "last_name": "Smith",
    "email": "jsmith@example.com"
  },
  "request_id": "req_xyz789",
  "status": "success"
}

List of Resources​

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": [
    {
      "id": "user_abc123",
      "username": "jsmith",
      "first_name": "John",
      "last_name": "Smith"
    },
    {
      "id": "user_def456",
      "username": "jdoe",
      "first_name": "Jane",
      "last_name": "Doe"
    }
  ],
  "page_size": 25,
  "next_start_key": "user_ghi789",
  "request_id": "req_xyz789",
  "status": "success"
}

Pagination Fields​

When listing resources:

  • page_size: Number of items returned
  • next_start_key: Key to use for fetching the next page (absent if no more pages)
  • start_key: Key of the first item in current page

Status Codes Reference​

Success Codes (2xx)​

CodeMeaningCommon Scenario
200OKRequest succeeded
201CreatedResource created
204No ContentSuccessful, empty response (DELETE)

Client Error Codes (4xx)​

CodeMeaningCommon Scenario
400Bad RequestInvalid parameters
401UnauthorizedAuthentication failed
403ForbiddenInsufficient permissions
404Not FoundResource doesn't exist
409ConflictResource conflict
429Too Many RequestsRate limited

Server Error Codes (5xx)​

CodeMeaningCommon Scenario
500Server ErrorInternal service error
503Service UnavailableMaintenance/outage

Error Responses​

Standard Error Format​

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

401 Unauthorized​

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

404 Not Found​

{
  "data": {
    "message": "bad identifier"
  },
  "error": "404",
  "message": "bad_identifier",
  "status": "error"
}

400 Bad Request​

{
  "data": {
    "message": "validation failed",
    "errors": {
      "username": "is required"
    }
  },
  "error": "400",
  "status": "error"
}

Parsing Responses​

Python​

import requests

response = requests.get(
    f'https://api.audian.com:8443/v2/accounts/{ACCOUNT_ID}/users',
    headers={'X-Auth-Token': API_KEY}
)

data = response.json()

if data.get('status') == 'success':
    users = data['data']
    print(f"Found {len(users)} users")
else:
    error = data.get('data', {}).get('message', 'Unknown error')
    print(f"Error: {error}")

Node.js​

const response = await fetch(
  `https://api.audian.com:8443/v2/accounts/${ACCOUNT_ID}/users`,
  {
    headers: { 'X-Auth-Token': API_KEY }
  }
);

const json = await response.json();

if (json.status === 'success') {
  const users = json.data;
  console.log(`Found ${users.length} users`);
} else {
  console.error(`Error: ${json.data?.message || 'Unknown error'}`);
}

Response Headers​

All responses include standard headers:

Content-Type: application/json
X-Request-ID: req_abc123

Empty Responses​

Some operations return empty success responses:

# Response for DELETE
HTTP/1.1 204 No Content

Or:

{
  "auth_token": "eyJhbGciOiJSUzI1...",
  "data": {},
  "request_id": "req_delete_123",
  "status": "success"
}

Best Practices​

Do's ✓​

  • Always check the status field first
  • Use request_id when contacting support
  • Handle both success and error cases
  • Parse timestamps correctly
  • Check for next_start_key in list responses

Don'ts ✗​

  • Don't assume HTTP status code equals API success
  • Don't ignore error messages in the data field
  • Don't skip error handling

Next Steps​