Error Codes¶

This reference documents all error codes returned by the AG2Trust API.

Error Response Format¶

All errors follow a consistent format:

{
  "error": "Human-readable error message",
  "error_code": "MACHINE_READABLE_CODE",
  "details": {
    "additional": "context"
  }
}

Authentication Errors (4xx)¶

INVALID_API_KEY¶

HTTP Status: 401 Unauthorized

{
  "error": "Invalid or missing API key",
  "error_code": "INVALID_API_KEY"
}

Causes: - Missing X-API-Key header - Malformed API key - API key doesn't exist - API key has been revoked

Solutions: 1. Verify header name is exactly X-API-Key 2. Check for extra whitespace in key 3. Confirm key exists in Dashboard 4. Generate a new key if revoked

AGENT_NOT_FOUND¶

HTTP Status: 403 Forbidden or 404 Not Found

{
  "error": "Agent not found or not owned by customer",
  "error_code": "AGENT_NOT_FOUND"
}

Causes: - Agent ID doesn't exist - Agent belongs to different organization - Agent was deleted

Solutions: 1. Verify agent ID is correct 2. Use GET /api/v1/agents to list your agents 3. Check agent exists in Dashboard

ENDPOINT_NOT_FOUND¶

HTTP Status: 404 Not Found

{
  "error": "Endpoint not found",
  "error_code": "ENDPOINT_NOT_FOUND"
}

Causes: - Endpoint slug doesn't exist - No agent type with that endpoint slug - Agent type not assigned to your organization

Solutions: 1. Verify endpoint slug in Dashboard 2. Check Agent Types configuration 3. Ensure agents of that type are deployed

Request Errors (4xx)¶

AGENT_NOT_RUNNING¶

HTTP Status: 400 Bad Request

{
  "error": "Agent is not running",
  "error_code": "AGENT_NOT_RUNNING",
  "details": {
    "agent_id": "uuid",
    "status": "stopped"
  }
}

Causes: - Agent is stopped - Agent is in error state - Agent is still starting

Solutions: 1. Start the agent via Dashboard or API 2. Check agent logs for errors 3. Wait for agent to reach "running" status

MESSAGE_TOO_LONG¶

HTTP Status: 400 Bad Request

{
  "error": "Message exceeds maximum length",
  "error_code": "MESSAGE_TOO_LONG",
  "details": {
    "max_length": 10000,
    "actual_length": 15234
  }
}

Causes: - Message content exceeds 10,000 characters

Solutions: 1. Truncate or split the message 2. Summarize content before sending 3. Use file uploads for large content (when available)

WEBHOOK_INVALID_URL¶

HTTP Status: 400 Bad Request

{
  "error": "Invalid webhook URL",
  "error_code": "WEBHOOK_INVALID_URL",
  "details": {
    "url": "http://example.com/webhook",
    "reason": "HTTPS required"
  }
}

Causes: - URL uses HTTP instead of HTTPS - Malformed URL - Invalid domain

Solutions: 1. Use HTTPS for webhook URL 2. Verify URL format 3. Ensure domain is publicly accessible

INVALID_REQUEST¶

HTTP Status: 400 Bad Request

{
  "error": "Invalid request body",
  "error_code": "INVALID_REQUEST",
  "details": {
    "field": "message",
    "reason": "Required field missing"
  }
}

Causes: - Missing required fields - Invalid JSON syntax - Wrong data types

Solutions: 1. Check request body format 2. Include all required fields 3. Validate JSON syntax

Rate Limit Errors (429)¶

RATE_LIMIT_EXCEEDED¶

HTTP Status: 429 Too Many Requests

{
  "error": "Rate limit exceeded",
  "error_code": "RATE_LIMIT_EXCEEDED",
  "details": {
    "limit": 60,
    "reset_at": "2025-01-15T10:31:00Z",
    "retry_after": 15
  }
}

Causes: - Too many requests in time window - Organization limit exceeded - Per-agent limit exceeded

Solutions: 1. Implement retry with backoff 2. Use Retry-After header 3. Reduce request frequency 4. Upgrade plan for higher limits

See Rate Limits for handling strategies.

Server Errors (5xx)¶

NO_AGENTS_AVAILABLE¶

HTTP Status: 503 Service Unavailable

{
  "error": "No agents available",
  "error_code": "NO_AGENTS_AVAILABLE",
  "details": {
    "endpoint": "support",
    "reason": "All agents busy"
  }
}

Headers:

Retry-After: 5

Causes: - All agents are busy - All agents are offline - No agents deployed for endpoint

Solutions: 1. Retry after delay (use Retry-After header) 2. Start more agents 3. Scale up deployments 4. Check agent health in Dashboard

AGENT_TIMEOUT¶

HTTP Status: 504 Gateway Timeout

{
  "error": "Agent did not respond in time",
  "error_code": "AGENT_TIMEOUT",
  "details": {
    "timeout_seconds": 60
  }
}

Causes: - Agent processing took too long - LLM provider timeout - Agent container issues

Solutions: 1. Use async mode with webhooks for long tasks 2. Simplify the request 3. Check agent logs 4. Verify LLM provider status

INTERNAL_ERROR¶

HTTP Status: 500 Internal Server Error

{
  "error": "An internal error occurred",
  "error_code": "INTERNAL_ERROR",
  "details": {
    "request_id": "req_abc123"
  }
}

Causes: - System error - Database issue - Unexpected condition

Solutions: 1. Retry the request 2. Note the request_id for support 3. Check status.ag2trust.com 4. Contact support if persistent

Error Handling Best Practices¶

1. Handle by Error Code¶

response = requests.post(url, json=payload, headers=headers)

if not response.ok:
    error = response.json()
    code = error.get("error_code")

    if code == "RATE_LIMIT_EXCEEDED":
        handle_rate_limit(response.headers)
    elif code == "AGENT_NOT_RUNNING":
        start_agent_and_retry()
    elif code == "NO_AGENTS_AVAILABLE":
        wait_and_retry(response.headers.get("Retry-After", 5))
    else:
        log_error(error)
        raise APIError(error)

2. Implement Retry Logic¶

RETRYABLE_CODES = {
    "RATE_LIMIT_EXCEEDED",
    "NO_AGENTS_AVAILABLE",
    "AGENT_TIMEOUT",
    "INTERNAL_ERROR"
}

def should_retry(error_code):
    return error_code in RETRYABLE_CODES

3. Log Request IDs¶

def log_error(response):
    error = response.json()
    request_id = error.get("details", {}).get("request_id")
    logger.error(
        f"API Error: {error['error_code']} "
        f"Request ID: {request_id}"
    )

4. Surface User-Friendly Messages¶

ERROR_MESSAGES = {
    "AGENT_NOT_RUNNING": "The assistant is currently unavailable. Please try again.",
    "NO_AGENTS_AVAILABLE": "All assistants are busy. Please wait a moment.",
    "RATE_LIMIT_EXCEEDED": "Too many requests. Please slow down.",
}

def get_user_message(error_code):
    return ERROR_MESSAGES.get(
        error_code,
        "Something went wrong. Please try again."
    )

Complete Error Code Reference¶

Getting Help¶

If you encounter persistent errors:

1. Check status.ag2trust.com for outages
2. Review agent logs in the Dashboard
3. Include request_id when contacting support
4. Describe the steps to reproduce the error