Error Reference

Complete reference for all FAOS API error codes, HTTP status codes, and recommended handling strategies.

Error Response Format

All API errors follow a consistent JSON structure:

{
  "error": {
    "code": "agent_not_found",
    "message": "Agent with ID 'agt_abc123' does not exist",
    "type": "resource_error",
    "param": "agent_id",
    "request_id": "req_xyz789",
    "documentation_url": "https://docs.faosx.ai/api/errors#agent_not_found"
  }
}

Error Object Fields

Field	Type	Description
code	string	Machine-readable error code
message	string	Human-readable error description
type	string	Error category (see below)
param	string	Parameter that caused the error (if applicable)
request_id	string	Unique request identifier for support
documentation_url	string	Link to relevant documentation

Error Types

Type	Description	HTTP Status Range
authentication_error	Authentication failed	401
authorization_error	Insufficient permissions	403
resource_error	Resource not found or deleted	404
validation_error	Invalid request parameters	400, 422
rate_limit_error	Too many requests	429
server_error	Internal server error	500-599
integration_error	External service failure	502, 503

Authentication Errors (401)

invalid_token

Message: "The API key or access token is invalid or expired"

Cause: Token is malformed, expired, or revoked

Solution:

• Verify your API key is correct
• Check if token has expired (OAuth access tokens expire after 1 hour)
• Use refresh token to get new access token
• Regenerate API key if compromised

Example:

{
  "error": {
    "code": "invalid_token",
    "message": "The access token expired at 2025-12-21T10:00:00Z",
    "type": "authentication_error",
    "expires_at": "2025-12-21T10:00:00Z"
  }
}

missing_authentication

Message: "No authentication credentials provided"

Cause: Request missing Authorization header

Solution: Include API key in request header

curl https://api.faosx.ai/v1/agents \
  -H "Authorization: Bearer sk_live_abc123..."

Authorization Errors (403)

insufficient_scope

Message: "The access token lacks required scope: 'agents:write'"

Cause: OAuth token missing necessary permission

Solution: Request token with additional scopes during OAuth flow

tier_restriction

Message: "This feature requires Business tier or higher"

Cause: Attempting to use feature not available in current tier

Solution: Upgrade workspace tier or use tier-appropriate features

Example:

{
  "error": {
    "code": "tier_restriction",
    "message": "L4 autonomy requires Business tier or higher",
    "type": "authorization_error",
    "current_tier": "starter",
    "required_tier": "business",
    "upgrade_url": "https://app.faosx.ai/upgrade"
  }
}

guardrail_violation

Message: "Action blocked by agent guardrails"

Cause: Agent attempted action prohibited by guardrail configuration

Solution:

• Review agent guardrail settings
• Adjust guardrails if action should be permitted
• Use approval workflow for sensitive actions

Resource Errors (404)

agent_not_found

Message: "Agent with ID 'agt_abc123' does not exist"

Cause: Agent ID doesn't exist or was deleted

Solution: Verify agent ID, list agents to find correct ID

workflow_not_found

Message: "Workflow with ID 'wfl_abc123' does not exist"

Cause: Workflow ID doesn't exist or was deleted

Solution: Verify workflow ID, check if workflow was deleted

webhook_not_found

Message: "Webhook with ID 'hook_abc123' does not exist"

Cause: Webhook ID doesn't exist or was deleted

Solution: List webhooks to find correct ID

execution_not_found

Message: "Execution with ID 'exec_abc123' does not exist"

Cause: Execution ID doesn't exist or expired (executions expire after 30 days)

Solution: Verify execution ID, check if execution is older than retention period

Validation Errors (400, 422)

invalid_request_body

Message: "Request body is not valid JSON"

Cause: Malformed JSON in request body

Solution: Validate JSON syntax before sending

missing_required_field

Message: "Missing required field: 'name'"

Cause: Required parameter not provided

Solution: Include all required fields in request

Example:

{
  "error": {
    "code": "missing_required_field",
    "message": "Missing required field: 'name'",
    "type": "validation_error",
    "param": "name",
    "required_fields": ["name", "type", "ontology"]
  }
}

invalid_parameter

Message: "Invalid value for 'autonomy_level': must be L1, L2, L3, or L4"

Cause: Parameter value doesn't match expected format or enum

Solution: Check API documentation for valid parameter values

invalid_autonomy_level

Message: "Invalid autonomy level 'L5'"

Cause: Autonomy level must be L1, L2, L3, or L4

Solution: Use valid autonomy level (L1-L4)

invalid_step_config

Message: "Workflow step configuration is invalid"

Cause: Workflow step missing required fields or has invalid structure

Solution: Review workflow step schema in documentation

circular_dependency

Message: "Workflow contains circular references"

Cause: Workflow steps create infinite loop

Solution: Review workflow step flow to eliminate cycles

invalid_url

Message: "Webhook URL must be a valid HTTPS URL"

Cause: Webhook URL is malformed or not HTTPS

Solution: Ensure webhook URL uses HTTPS protocol

invalid_event_type

Message: "Unknown event type 'agent.invalid.event'"

Cause: Webhook subscribed to non-existent event type

Solution: Use valid event types from documentation

Rate Limit Errors (429)

rate_limit_exceeded

Message: "Rate limit exceeded for endpoint"

Cause: Too many requests in time window

Solution:

• Implement exponential backoff
• Reduce request frequency
• Consider upgrading tier for higher limits

Example:

{
  "error": {
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded: 60 requests per minute",
    "type": "rate_limit_error",
    "limit": 60,
    "remaining": 0,
    "reset_at": "2025-12-21T10:35:00Z"
  }
}

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1703168400
Retry-After: 42

Execution Errors (408, 409, 500)

execution_timeout

Message: "Agent execution exceeded timeout limit"

Cause: Execution took longer than configured timeout

Solution:

• Increase timeout setting
• Optimize agent workflow
• Break complex tasks into smaller steps

agent_not_active

Message: "Agent is currently paused or in training mode"

Cause: Attempted to execute paused or training agent

Solution: Activate agent before execution

Example:

{
  "error": {
    "code": "agent_not_active",
    "message": "Agent is currently paused",
    "type": "resource_error",
    "agent_status": "paused",
    "agent_id": "agt_abc123"
  }
}

workflow_timeout

Message: "Workflow execution exceeded timeout limit of 300 seconds"

Cause: Workflow took longer than configured timeout

Solution: Increase workflow timeout or optimize steps

step_failed

Message: "Workflow step 'step_3' failed"

Cause: Individual workflow step encountered error

Solution: Check step logs, review step configuration

Example:

{
  "error": {
    "code": "step_failed",
    "message": "Workflow step 'step_3' failed: CRM API error",
    "type": "server_error",
    "step_id": "step_3",
    "step_name": "Update CRM",
    "underlying_error": {
      "code": "external_api_error",
      "message": "CRM API returned 503"
    }
  }
}

Integration Errors (502, 503)

external_api_error

Message: "External service returned error"

Cause: Integrated third-party service failed

Solution:

• Check integration service status
• Retry request
• Contact integration provider

integration_not_configured

Message: "Integration 'salesforce' is not configured"

Cause: Workflow or agent requires integration that isn't set up

Solution: Configure required integration in workspace settings

integration_auth_failed

Message: "Integration authentication failed"

Cause: Integration credentials expired or invalid

Solution: Reconnect integration with fresh credentials

Server Errors (500-599)

internal_server_error

Message: "An unexpected error occurred"

Cause: Unexpected server-side error

Solution:

• Retry request with exponential backoff
• Contact support if persists, provide request_id

service_unavailable

Message: "Service temporarily unavailable"

Cause: FAOS service experiencing issues or maintenance

Solution: Retry with exponential backoff, check status page

Error Handling Best Practices

1. Always Check HTTP Status

const response = await fetch('https://api.faosx.ai/v1/agents', {
  headers: { 'Authorization': `Bearer ${apiKey}` }
});

if (!response.ok) {
  const error = await response.json();
  handleError(error, response.status);
}

2. Implement Retry Logic

async function apiRequestWithRetry(url, options, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      const response = await fetch(url, options);

      if (response.ok) {
        return await response.json();
      }

      // Don't retry 4xx errors (except 429)
      if (response.status >= 400 && response.status < 500 && response.status !== 429) {
        throw new Error(`Client error: ${response.status}`);
      }

      // Exponential backoff
      if (attempt < maxRetries - 1) {
        await sleep(Math.pow(2, attempt) * 1000);
      }
    } catch (err) {
      if (attempt === maxRetries - 1) throw err;
    }
  }
}

3. Handle Rate Limits

async function handleRateLimit(response) {
  if (response.status === 429) {
    const retryAfter = response.headers.get('Retry-After');
    const resetAt = response.headers.get('X-RateLimit-Reset');

    const waitTime = retryAfter
      ? parseInt(retryAfter) * 1000
      : (parseInt(resetAt) * 1000) - Date.now();

    await sleep(waitTime);
    return true; // Retry
  }
  return false;
}

4. Log Request IDs

function logError(error, response) {
  console.error({
    request_id: error.error.request_id,
    code: error.error.code,
    message: error.error.message,
    status: response.status,
    timestamp: new Date().toISOString()
  });
}

5. Graceful Degradation

async function executeAgentWithFallback(agentId, input) {
  try {
    return await faos.agents.execute(agentId, { input });
  } catch (error) {
    if (error.code === 'agent_not_active') {
      // Fall back to alternate agent
      return await faos.agents.execute(fallbackAgentId, { input });
    }

    if (error.code === 'rate_limit_exceeded') {
      // Queue for later
      await queue.add('agent-execution', { agentId, input });
      return { queued: true };
    }

    throw error;
  }
}

Error Code Quick Reference

Authentication (401)

• invalid_token - Token invalid or expired
• missing_authentication - No auth header provided

Authorization (403)

• insufficient_scope - Missing required OAuth scope
• tier_restriction - Feature requires higher tier
• guardrail_violation - Action blocked by guardrails

Resources (404)

• agent_not_found - Agent doesn't exist
• workflow_not_found - Workflow doesn't exist
• webhook_not_found - Webhook doesn't exist
• execution_not_found - Execution doesn't exist

Validation (400, 422)

• invalid_request_body - Malformed JSON
• missing_required_field - Required parameter missing
• invalid_parameter - Parameter value invalid
• invalid_autonomy_level - Invalid L1-L4 level
• invalid_step_config - Workflow step invalid
• circular_dependency - Workflow has cycles
• invalid_url - URL malformed
• invalid_event_type - Unknown event type

Rate Limiting (429)

• rate_limit_exceeded - Too many requests

Execution (408, 409, 500)

• execution_timeout - Execution took too long
• agent_not_active - Agent paused or training
• workflow_timeout - Workflow took too long
• step_failed - Workflow step failed

Integration (502, 503)

• external_api_error - Third-party service failed
• integration_not_configured - Integration not set up
• integration_auth_failed - Integration auth expired

Server (500-599)

• internal_server_error - Unexpected server error
• service_unavailable - Service down or maintenance

Getting Help

If you encounter persistent errors:

1. Check Status Page: status.faosx.ai
2. Review Documentation: Each error includes documentation_url
3. Contact Support: Include request_id from error response
4. Community: Discord for community help

Next Steps

• Agents API - Create and manage agents
• Workflows API - Automate processes
• Webhooks - Real-time notifications
• Authentication - Auth setup