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
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
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