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: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
UNAUTHORIZED
UNAUTHORIZED
INVALID_CREDENTIALS
INVALID_CREDENTIALS
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
- Verify your credentials are correct
- Check basic authentication header format
- Ensure credentials are properly encoded
- Contact support if credentials are correct but still failing
TOKEN_EXPIRED
TOKEN_EXPIRED
HTTP Status: 401Description: Access token has expiredCauses:
- Access token past expiration time
- Refresh token also expired
- Token not refreshed before expiration
- 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
Permission Errors
FORBIDDEN
FORBIDDEN
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
- 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
ACCESS_DENIED
ACCESS_DENIED
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
- 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
Validation Errors
VALIDATION_ERROR
VALIDATION_ERROR
HTTP Status: 400Description: Invalid request parameters or validation failedCauses:
- Missing required fields
- Invalid data types
- Values outside allowed ranges
- Invalid email formats
- Malformed JSON
- Check request body for required fields
- Verify data types match expected types
- Validate input before sending requests
- Check JSON syntax and formatting
MISSING_REQUIRED_FIELD
MISSING_REQUIRED_FIELD
HTTP Status: 400Description: Required field is missing from requestCauses:
- Required parameter not provided
- Empty required field
- Null required field
- Check API documentation for required fields
- Ensure all required parameters are included
- Verify field names match documentation
- Check for typos in field names
INVALID_FORMAT
INVALID_FORMAT
HTTP Status: 400Description: Invalid data formatCauses:
- Invalid email format
- Invalid date format
- Invalid UUID format
- Invalid JSON structure
- Check data format requirements
- Validate input before sending
- Use proper date formats (ISO 8601)
- Ensure valid email addresses
Resource Errors
NOT_FOUND
NOT_FOUND
HTTP Status: 404Description: Requested resource not foundCauses:
- Resource doesn’t exist
- Invalid resource ID
- Resource deleted or moved
- Wrong API endpoint
- Verify resource ID is correct
- Check if resource exists
- Verify you’re using the correct endpoint
- Check if resource was deleted
RESOURCE_EXISTS
RESOURCE_EXISTS
HTTP Status: 409Description: Resource already existsCauses:
- Trying to create duplicate resource
- Unique constraint violation
- Resource with same name exists
- Check if resource already exists
- Use different name or identifier
- Update existing resource instead
- Check for unique constraints
RESOURCE_CONFLICT
RESOURCE_CONFLICT
HTTP Status: 409Description: Resource conflictCauses:
- Concurrent modification
- Resource state conflict
- Dependency conflict
- Retry the operation
- Check resource state
- Resolve dependencies first
- Use optimistic locking
Rate Limiting Errors
RATE_LIMIT_EXCEEDED
RATE_LIMIT_EXCEEDED
HTTP Status: 429Description: Too many requests in time windowCauses:
- Exceeded requests per minute limit
- Burst limit exceeded
- Too many concurrent requests
- Implement exponential backoff
- Reduce request frequency
- Cache responses when possible
- Monitor rate limit headers
QUOTA_EXCEEDED
QUOTA_EXCEEDED
HTTP Status: 429Description: API quota exceededCauses:
- Monthly quota exceeded
- Daily quota exceeded
- Per-endpoint quota exceeded
- Check your quota usage
- Upgrade your plan if needed
- Optimize API usage
- Contact support for quota increase
Server Errors
INTERNAL_SERVER_ERROR
INTERNAL_SERVER_ERROR
HTTP Status: 500Description: Internal server errorCauses:
- Server-side processing error
- Database connection issues
- Third-party service failures
- Unexpected server state
- Retry the request after a delay
- Check API status page
- Contact support if error persists
- Implement proper error handling
SERVICE_UNAVAILABLE
SERVICE_UNAVAILABLE
Error Handling Best Practices
Client-Side Error Handling
Client-Side Error Handling
Retry Logic
Retry Logic
Error Logging
Error Logging
Troubleshooting Guide
Common Error Scenarios
Authentication Issues
Authentication Issues
Symptoms: 401 Unauthorized errorsCommon Causes:
- Expired access tokens
- Missing Authorization header
- Invalid token format
- Wrong credentials
- Implement automatic token refresh
- Check header format and token validity
- Verify credentials are correct
- Handle authentication errors gracefully
Rate Limiting Issues
Rate Limiting Issues
Symptoms: 429 Too Many Requests errorsCommon Causes:
- High request frequency
- Burst requests
- No rate limiting implementation
- Implement exponential backoff
- Cache responses when possible
- Monitor rate limit headers
- Reduce request frequency
Validation Issues
Validation Issues
Symptoms: 400 Bad Request errorsCommon Causes:
- Missing required fields
- Invalid data types
- Malformed JSON
- Invalid formats
- Validate input before sending
- Check required field documentation
- Verify data types and formats
- Test with API playground