> ## Documentation Index
> Fetch the complete documentation index at: https://doc-dev.weir.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Error Codes Reference

> Comprehensive error code reference and troubleshooting guide for Weir AI API v1.0.1

# Error Codes Reference

Comprehensive reference for all error codes returned by the Weir AI API v1.0.1, including descriptions, causes, and solutions.

## Error Response Format

All error responses follow this consistent format:

```json theme={null}
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details or validation errors"
  },
  "status": "error"
}
```

## HTTP Status Codes

<CardGroup cols={2}>
  <Card title="Client Errors (4xx)" icon="exclamation-triangle">
    * **400 Bad Request**: Invalid request parameters
    * **401 Unauthorized**: Authentication required
    * **403 Forbidden**: Insufficient permissions
    * **404 Not Found**: Resource not found
    * **409 Conflict**: Resource conflict
    * **429 Too Many Requests**: Rate limit exceeded
  </Card>

  <Card title="Server Errors (5xx)" icon="server">
    * **500 Internal Server Error**: Server-side error
    * **502 Bad Gateway**: Gateway error
    * **503 Service Unavailable**: Service temporarily unavailable
    * **504 Gateway Timeout**: Gateway timeout
  </Card>
</CardGroup>

## Authentication Errors

<AccordionGroup>
  <Accordion title="UNAUTHORIZED" icon="key">
    **HTTP Status**: 401

    **Description**: Invalid or expired authentication token

    **Causes**:

    * Missing Authorization header
    * Invalid access token format
    * Expired access token
    * Malformed Bearer token

    **Solutions**:

    * Check Authorization header format: `Bearer YOUR_TOKEN`
    * Refresh your access token
    * Re-authenticate if refresh token is also expired
    * Verify token format and ensure it's properly included

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "UNAUTHORIZED",
        "message": "Invalid or expired token",
        "details": "The provided access token is invalid or has expired"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="INVALID_CREDENTIALS" icon="ban">
    **HTTP Status**: 401

    **Description**: Invalid client credentials or user credentials

    **Causes**:

    * Incorrect client ID or secret key
    * Wrong username or password
    * Malformed basic authentication header
    * Invalid admin token

    **Solutions**:

    * Verify your credentials are correct
    * Check basic authentication header format
    * Ensure credentials are properly encoded
    * Contact support if credentials are correct but still failing

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "INVALID_CREDENTIALS",
        "message": "Invalid client credentials",
        "details": "The provided client ID or secret key is invalid"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="TOKEN_EXPIRED" icon="clock">
    **HTTP Status**: 401

    **Description**: Access token has expired

    **Causes**:

    * Access token past expiration time
    * Refresh token also expired
    * Token not refreshed before expiration

    **Solutions**:

    * Refresh your access token using the refresh token
    * Re-authenticate if refresh token is expired
    * Implement automatic token refresh
    * Check token expiration time before making requests

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "TOKEN_EXPIRED",
        "message": "Access token has expired",
        "details": "Please refresh your token or re-authenticate"
      },
      "status": "error"
    }
    ```
  </Accordion>
</AccordionGroup>

## Permission Errors

<AccordionGroup>
  <Accordion title="FORBIDDEN" icon="lock">
    **HTTP Status**: 403

    **Description**: Valid authentication but insufficient permissions

    **Causes**:

    * User lacks required role or permissions
    * Trying to access resource outside organization
    * Admin-only endpoint accessed with user token
    * Insufficient team permissions

    **Solutions**:

    * Check your user role and permissions
    * Contact your organization administrator for access
    * Verify you're using the correct API category
    * Ensure you have the required team permissions

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "FORBIDDEN",
        "message": "Insufficient permissions",
        "details": "Your account does not have permission to access this resource"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="ACCESS_DENIED" icon="ban">
    **HTTP Status**: 403

    **Description**: Access denied to requested resource

    **Causes**:

    * Resource belongs to different organization
    * User not member of required team
    * Resource is private or restricted
    * Admin privileges required

    **Solutions**:

    * Verify you have access to the resource
    * Check if you're a member of the required team
    * Contact resource owner for access
    * Use admin APIs if administrative access is needed

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "ACCESS_DENIED",
        "message": "Access denied to resource",
        "details": "You do not have access to this resource"
      },
      "status": "error"
    }
    ```
  </Accordion>
</AccordionGroup>

## Validation Errors

<AccordionGroup>
  <Accordion title="VALIDATION_ERROR" icon="exclamation-triangle">
    **HTTP Status**: 400

    **Description**: Invalid request parameters or validation failed

    **Causes**:

    * Missing required fields
    * Invalid data types
    * Values outside allowed ranges
    * Invalid email formats
    * Malformed JSON

    **Solutions**:

    * Check request body for required fields
    * Verify data types match expected types
    * Validate input before sending requests
    * Check JSON syntax and formatting

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "VALIDATION_ERROR",
        "message": "Invalid request parameters",
        "details": {
          "name": "Team name is required and must be between 2-50 characters",
          "email": "Invalid email format"
        }
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="MISSING_REQUIRED_FIELD" icon="exclamation">
    **HTTP Status**: 400

    **Description**: Required field is missing from request

    **Causes**:

    * Required parameter not provided
    * Empty required field
    * Null required field

    **Solutions**:

    * Check API documentation for required fields
    * Ensure all required parameters are included
    * Verify field names match documentation
    * Check for typos in field names

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "MISSING_REQUIRED_FIELD",
        "message": "Required field is missing",
        "details": "The 'name' field is required for team creation"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="INVALID_FORMAT" icon="code">
    **HTTP Status**: 400

    **Description**: Invalid data format

    **Causes**:

    * Invalid email format
    * Invalid date format
    * Invalid UUID format
    * Invalid JSON structure

    **Solutions**:

    * Check data format requirements
    * Validate input before sending
    * Use proper date formats (ISO 8601)
    * Ensure valid email addresses

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "INVALID_FORMAT",
        "message": "Invalid data format",
        "details": "Email address must be a valid email format"
      },
      "status": "error"
    }
    ```
  </Accordion>
</AccordionGroup>

## Resource Errors

<AccordionGroup>
  <Accordion title="NOT_FOUND" icon="search">
    **HTTP Status**: 404

    **Description**: Requested resource not found

    **Causes**:

    * Resource doesn't exist
    * Invalid resource ID
    * Resource deleted or moved
    * Wrong API endpoint

    **Solutions**:

    * Verify resource ID is correct
    * Check if resource exists
    * Verify you're using the correct endpoint
    * Check if resource was deleted

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "NOT_FOUND",
        "message": "Resource not found",
        "details": "The requested team does not exist or you do not have access to it"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="RESOURCE_EXISTS" icon="exclamation">
    **HTTP Status**: 409

    **Description**: Resource already exists

    **Causes**:

    * Trying to create duplicate resource
    * Unique constraint violation
    * Resource with same name exists

    **Solutions**:

    * Check if resource already exists
    * Use different name or identifier
    * Update existing resource instead
    * Check for unique constraints

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "RESOURCE_EXISTS",
        "message": "Resource already exists",
        "details": "A team with this name already exists in your organization"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="RESOURCE_CONFLICT" icon="exclamation-triangle">
    **HTTP Status**: 409

    **Description**: Resource conflict

    **Causes**:

    * Concurrent modification
    * Resource state conflict
    * Dependency conflict

    **Solutions**:

    * Retry the operation
    * Check resource state
    * Resolve dependencies first
    * Use optimistic locking

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "RESOURCE_CONFLICT",
        "message": "Resource conflict",
        "details": "The resource has been modified by another user"
      },
      "status": "error"
    }
    ```
  </Accordion>
</AccordionGroup>

## Rate Limiting Errors

<AccordionGroup>
  <Accordion title="RATE_LIMIT_EXCEEDED" icon="clock">
    **HTTP Status**: 429

    **Description**: Too many requests in time window

    **Causes**:

    * Exceeded requests per minute limit
    * Burst limit exceeded
    * Too many concurrent requests

    **Solutions**:

    * Implement exponential backoff
    * Reduce request frequency
    * Cache responses when possible
    * Monitor rate limit headers

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Too many requests",
        "details": "Rate limit of 100 requests per minute exceeded"
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="QUOTA_EXCEEDED" icon="chart-line">
    **HTTP Status**: 429

    **Description**: API quota exceeded

    **Causes**:

    * Monthly quota exceeded
    * Daily quota exceeded
    * Per-endpoint quota exceeded

    **Solutions**:

    * Check your quota usage
    * Upgrade your plan if needed
    * Optimize API usage
    * Contact support for quota increase

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "QUOTA_EXCEEDED",
        "message": "API quota exceeded",
        "details": "Monthly quota of 10000 requests exceeded"
      },
      "status": "error"
    }
    ```
  </Accordion>
</AccordionGroup>

## Server Errors

<AccordionGroup>
  <Accordion title="INTERNAL_SERVER_ERROR" icon="server">
    **HTTP Status**: 500

    **Description**: Internal server error

    **Causes**:

    * Server-side processing error
    * Database connection issues
    * Third-party service failures
    * Unexpected server state

    **Solutions**:

    * Retry the request after a delay
    * Check API status page
    * Contact support if error persists
    * Implement proper error handling

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "INTERNAL_SERVER_ERROR",
        "message": "Internal server error",
        "details": "An unexpected error occurred. Please try again later."
      },
      "status": "error"
    }
    ```
  </Accordion>

  <Accordion title="SERVICE_UNAVAILABLE" icon="wrench">
    **HTTP Status**: 503

    **Description**: Service temporarily unavailable

    **Causes**:

    * Maintenance in progress
    * High load conditions
    * Service degradation
    * Planned downtime

    **Solutions**:

    * Wait and retry after delay
    * Check API status page
    * Implement exponential backoff
    * Monitor service status

    **Example Response**:

    ```json theme={null}
    {
      "error": {
        "code": "SERVICE_UNAVAILABLE",
        "message": "Service temporarily unavailable",
        "details": "The service is currently undergoing maintenance"
      },
      "status": "error"
    }
    ```
  </Accordion>
</AccordionGroup>

## Error Handling Best Practices

<AccordionGroup>
  <Accordion title="Client-Side Error Handling" icon="code">
    ```javascript theme={null}
    try {
      const response = await fetch(url, options);
      
      if (!response.ok) {
        const errorData = await response.json();
        
        switch (errorData.error.code) {
          case 'UNAUTHORIZED':
            // Refresh token or re-authenticate
            await refreshToken();
            break;
          case 'RATE_LIMIT_EXCEEDED':
            // Implement exponential backoff
            await delay(Math.pow(2, retryCount) * 1000);
            break;
          case 'VALIDATION_ERROR':
            // Show validation errors to user
            showValidationErrors(errorData.error.details);
            break;
          default:
            // Show generic error message
            showError(errorData.error.message);
        }
      }
    } catch (error) {
      // Handle network errors
      console.error('Network error:', error);
    }
    ```
  </Accordion>

  <Accordion title="Retry Logic" icon="refresh">
    ```javascript theme={null}
    async function makeRequestWithRetry(url, options, maxRetries = 3) {
      for (let attempt = 1; attempt <= maxRetries; attempt++) {
        try {
          const response = await fetch(url, options);
          
          if (response.ok) {
            return await response.json();
          }
          
          const errorData = await response.json();
          
          // Don't retry client errors (4xx)
          if (response.status >= 400 && response.status < 500) {
            throw new Error(errorData.error.message);
          }
          
          // Retry server errors (5xx) and rate limits
          if (attempt === maxRetries) {
            throw new Error(errorData.error.message);
          }
          
          // Exponential backoff
          await delay(Math.pow(2, attempt) * 1000);
          
        } catch (error) {
          if (attempt === maxRetries) {
            throw error;
          }
          await delay(Math.pow(2, attempt) * 1000);
        }
      }
    }
    ```
  </Accordion>

  <Accordion title="Error Logging" icon="clipboard-list">
    ```javascript theme={null}
    function logError(error, context) {
      const errorLog = {
        timestamp: new Date().toISOString(),
        error: {
          code: error.code,
          message: error.message,
          details: error.details
        },
        context: context,
        userAgent: navigator.userAgent,
        url: window.location.href
      };
      
      // Send to logging service
      fetch('/api/logs/error', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(errorLog)
      });
      
      // Also log to console in development
      if (process.env.NODE_ENV === 'development') {
        console.error('API Error:', errorLog);
      }
    }
    ```
  </Accordion>
</AccordionGroup>

## Troubleshooting Guide

<Steps>
  <Step title="Check HTTP Status Code" icon="search">
    Look at the HTTP status code to understand the general category of error.
  </Step>

  <Step title="Read Error Message" icon="eye">
    Read the error message for a human-readable description of the problem.
  </Step>

  <Step title="Check Error Details" icon="list">
    Review the error details for specific information about what went wrong.
  </Step>

  <Step title="Implement Solution" icon="wrench">
    Apply the appropriate solution based on the error code and details.
  </Step>

  <Step title="Test and Verify" icon="check">
    Test your fix to ensure the error is resolved.
  </Step>
</Steps>

## Common Error Scenarios

<AccordionGroup>
  <Accordion title="Authentication Issues" icon="key">
    **Symptoms**: 401 Unauthorized errors

    **Common Causes**:

    * Expired access tokens
    * Missing Authorization header
    * Invalid token format
    * Wrong credentials

    **Solutions**:

    * Implement automatic token refresh
    * Check header format and token validity
    * Verify credentials are correct
    * Handle authentication errors gracefully
  </Accordion>

  <Accordion title="Rate Limiting Issues" icon="clock">
    **Symptoms**: 429 Too Many Requests errors

    **Common Causes**:

    * High request frequency
    * Burst requests
    * No rate limiting implementation

    **Solutions**:

    * Implement exponential backoff
    * Cache responses when possible
    * Monitor rate limit headers
    * Reduce request frequency
  </Accordion>

  <Accordion title="Validation Issues" icon="exclamation-triangle">
    **Symptoms**: 400 Bad Request errors

    **Common Causes**:

    * Missing required fields
    * Invalid data types
    * Malformed JSON
    * Invalid formats

    **Solutions**:

    * Validate input before sending
    * Check required field documentation
    * Verify data types and formats
    * Test with API playground
  </Accordion>
</AccordionGroup>

<Tip>
  **Pro Tip**: Always implement comprehensive error handling in your applications. Use the error codes to provide specific feedback to users and implement appropriate retry logic for transient errors.
</Tip>