Error Handling

All ATHENA API errors follow a consistent format.

Error Response Format

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: user_id",
    "param": "user_id",
    "doc_url": "https://docs.athenatrust.ai/errors"
  }
}

Field	Description
code	Machine-readable error code
message	Human-readable description
param	Parameter that caused error (if applicable)
doc_url	Link to documentation

HTTP Status Codes

Status	Meaning	When Returned
200	Success	Request completed
201	Created	Resource created
400	Bad Request	Invalid parameters
401	Unauthorized	Invalid/missing API key
403	Forbidden	Insufficient permissions
404	Not Found	Resource doesn't exist
429	Too Many Requests	Rate limit exceeded
500	Internal Error	Server error

Error Codes

Authentication Errors

Code	HTTP	Description
authentication_failed	401	Invalid or missing API key
api_key_revoked	401	API key has been revoked
api_key_expired	401	API key has expired

Validation Errors

Code	HTTP	Description
invalid_request	400	Request body is invalid
missing_parameter	400	Required parameter missing
invalid_parameter	400	Parameter value is invalid

Rate Limit Errors

Code	HTTP	Description
rate_limit_exceeded	429	Too many requests

Resource Errors

Code	HTTP	Description
not_found	404	Resource doesn't exist
conflict	409	Resource already exists

Server Errors

Code	HTTP	Description
internal_error	500	Unexpected server error
service_unavailable	503	Temporarily unavailable

Handling Errors

JavaScript

import { 
  AthenaError, 
  AuthenticationError, 
  RateLimitError,
  ValidationError 
} from '@athena-ai/sdk';

try {
  await athena.calibrate.analyze({ ... });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error('Invalid API key');
  } else if (error instanceof RateLimitError) {
    console.log(`Retry after ${error.retryAfter}s`);
    await sleep(error.retryAfter * 1000);
    // Retry...
  } else if (error instanceof ValidationError) {
    console.error(`Invalid: ${error.param}`);
  } else if (error instanceof AthenaError) {
    console.error(`API error: ${error.code}`);
  } else {
    throw error;
  }
}

Python

from athena import (
    Athena,
    AuthenticationError,
    RateLimitError,
    ValidationError,
    AthenaError
)

try:
    result = athena.calibrate.analyze(...)
except AuthenticationError:
    print("Invalid API key")
except RateLimitError as e:
    print(f"Retry after {e.retry_after}s")
    time.sleep(e.retry_after)
    # Retry...
except ValidationError as e:
    print(f"Invalid: {e.param}")
except AthenaError as e:
    print(f"API error: {e.code}")

Retry Logic

Rate Limits

When you receive a 429 error:

HTTP/1.1 429 Too Many Requests
Retry-After: 60

Wait for the Retry-After duration, then retry.

Server Errors

For 5xx errors, use exponential backoff:

async function retryWithBackoff(fn, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await fn();
    } catch (error) {
      if (error.status >= 500 && i < maxRetries - 1) {
        const delay = Math.pow(2, i) * 1000; // 1s, 2s, 4s
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw error;
    }
  }
}

Debugging

Request ID

Every response includes a request ID:

X-Request-Id: req_abc123xyz

Include this when contacting support.

Verbose Errors (Development)

During development, errors include additional context:

{
  "error": {
    "code": "invalid_parameter",
    "message": "confidence must be between 0 and 1",
    "param": "confidence",
    "value": 1.5,
    "doc_url": "https://docs.athenatrust.ai/errors"
  }
}

---

Next: Changelog