Skip to main content

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:
{
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error message",
    "details": "Additional error details or validation errors"
  },
  "status": "error"
}

HTTP Status Codes

Client Errors (4xx)

  • 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

Server Errors (5xx)

  • 500 Internal Server Error: Server-side error
  • 502 Bad Gateway: Gateway error
  • 503 Service Unavailable: Service temporarily unavailable
  • 504 Gateway Timeout: Gateway timeout

Authentication Errors

HTTP Status: 401Description: Invalid or expired authentication tokenCauses:
  • 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:
{
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid or expired token",
    "details": "The provided access token is invalid or has expired"
  },
  "status": "error"
}
HTTP Status: 401Description: Invalid client credentials or user credentialsCauses:
  • 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:
{
  "error": {
    "code": "INVALID_CREDENTIALS",
    "message": "Invalid client credentials",
    "details": "The provided client ID or secret key is invalid"
  },
  "status": "error"
}
HTTP Status: 401Description: Access token has expiredCauses:
  • 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:
{
  "error": {
    "code": "TOKEN_EXPIRED",
    "message": "Access token has expired",
    "details": "Please refresh your token or re-authenticate"
  },
  "status": "error"
}

Permission Errors

HTTP Status: 403Description: Valid authentication but insufficient permissionsCauses:
  • 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:
{
  "error": {
    "code": "FORBIDDEN",
    "message": "Insufficient permissions",
    "details": "Your account does not have permission to access this resource"
  },
  "status": "error"
}
HTTP Status: 403Description: Access denied to requested resourceCauses:
  • 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:
{
  "error": {
    "code": "ACCESS_DENIED",
    "message": "Access denied to resource",
    "details": "You do not have access to this resource"
  },
  "status": "error"
}

Validation Errors

HTTP Status: 400Description: Invalid request parameters or validation failedCauses:
  • 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:
{
  "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"
}
HTTP Status: 400Description: Required field is missing from requestCauses:
  • 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:
{
  "error": {
    "code": "MISSING_REQUIRED_FIELD",
    "message": "Required field is missing",
    "details": "The 'name' field is required for team creation"
  },
  "status": "error"
}
HTTP Status: 400Description: Invalid data formatCauses:
  • 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:
{
  "error": {
    "code": "INVALID_FORMAT",
    "message": "Invalid data format",
    "details": "Email address must be a valid email format"
  },
  "status": "error"
}

Resource Errors

HTTP Status: 404Description: Requested resource not foundCauses:
  • 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:
{
  "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"
}
HTTP Status: 409Description: Resource already existsCauses:
  • 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:
{
  "error": {
    "code": "RESOURCE_EXISTS",
    "message": "Resource already exists",
    "details": "A team with this name already exists in your organization"
  },
  "status": "error"
}
HTTP Status: 409Description: Resource conflictCauses:
  • Concurrent modification
  • Resource state conflict
  • Dependency conflict
Solutions:
  • Retry the operation
  • Check resource state
  • Resolve dependencies first
  • Use optimistic locking
Example Response:
{
  "error": {
    "code": "RESOURCE_CONFLICT",
    "message": "Resource conflict",
    "details": "The resource has been modified by another user"
  },
  "status": "error"
}

Rate Limiting Errors

HTTP Status: 429Description: Too many requests in time windowCauses:
  • 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:
{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Too many requests",
    "details": "Rate limit of 100 requests per minute exceeded"
  },
  "status": "error"
}
HTTP Status: 429Description: API quota exceededCauses:
  • 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:
{
  "error": {
    "code": "QUOTA_EXCEEDED",
    "message": "API quota exceeded",
    "details": "Monthly quota of 10000 requests exceeded"
  },
  "status": "error"
}

Server Errors

HTTP Status: 500Description: Internal server errorCauses:
  • 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:
{
  "error": {
    "code": "INTERNAL_SERVER_ERROR",
    "message": "Internal server error",
    "details": "An unexpected error occurred. Please try again later."
  },
  "status": "error"
}
HTTP Status: 503Description: Service temporarily unavailableCauses:
  • 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:
{
  "error": {
    "code": "SERVICE_UNAVAILABLE",
    "message": "Service temporarily unavailable",
    "details": "The service is currently undergoing maintenance"
  },
  "status": "error"
}

Error Handling Best Practices

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);
}
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);
    }
  }
}
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);
  }
}

Troubleshooting Guide

Check HTTP Status Code

Look at the HTTP status code to understand the general category of error.

Read Error Message

Read the error message for a human-readable description of the problem.

Check Error Details

Review the error details for specific information about what went wrong.

Implement Solution

Apply the appropriate solution based on the error code and details.

Test and Verify

Test your fix to ensure the error is resolved.

Common Error Scenarios

Symptoms: 401 Unauthorized errorsCommon 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
Symptoms: 429 Too Many Requests errorsCommon 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
Symptoms: 400 Bad Request errorsCommon 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
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.