Error Handling
Understanding and handling API errors
All errors follow a consistent JSON format with HTTP status codes:
{
"success": false,
"error": {
"code": "INVALID_COMPOUND",
"message": "The compound ID is not recognized",
"details": {
"invalid_id": "unknown-123",
"valid_format": "compound-xxxxx"
}
},
"timestamp": "2024-01-15T10:30:45Z",
"request_id": "req_123abc789xyz"
}Tip: Always include the request_id when contacting support to help us investigate issues faster.
Bad Request
The request was malformed or missing required parameters.
Common causes:
- Invalid JSON
- Missing required fields
- Invalid query parameters
Solution: Check your request payload and ensure all required fields are included.
Unauthorized
The API key is missing, invalid, or expired.
Common causes:
- Missing Authorization header
- Invalid API key
- Expired credentials
Solution: Verify your API key is correct and included in the Authorization header.
Forbidden
The API key does not have permission to access this resource.
Common causes:
- Insufficient permissions
- API key restricted to specific endpoints
- Account suspended
Solution: Check your account permissions or contact support to upgrade your access.
Not Found
The requested resource does not exist.
Common causes:
- Invalid endpoint URL
- Resource ID not found
- Deleted resource
Solution: Verify the endpoint URL and resource ID are correct.
Too Many Requests
You have exceeded the rate limit for this endpoint.
Common causes:
- Exceeded per-minute limit
- Exceeded hourly burst limit
- Too many concurrent requests
Solution: Implement exponential backoff and respect the Retry-After header.
Internal Server Error
An unexpected error occurred on the server.
Common causes:
- Database connection failed
- Processing timeout
- Service unavailable
Solution: Retry your request after a short delay. Contact support if the issue persists.
Service Unavailable
The API is temporarily unavailable for maintenance.
Common causes:
- Scheduled maintenance
- Deployment in progress
- Server overloaded
Solution: Wait a few minutes and retry. Check our status page for updates.
The compound ID or name is not recognized in the database.
How to fix: Use the compounds search endpoint to find valid compound IDs.
The drug interaction check failed due to invalid drug combination.
How to fix: Verify that both drugs are in the supported database.
The clinical analysis could not be completed due to insufficient or invalid data.
How to fix: Check that all required biomarkers are included and properly formatted.
The provided symptom is not recognized in our medical database.
How to fix: Use common symptom descriptions or see the symptom checker endpoint for valid values.
The AI model took too long to process the request.
How to fix: Try again with a simpler query or fewer parameters.
Your account has exceeded its usage quota for this billing period.
How to fix: Upgrade your plan or contact sales to increase your quota.
1. Always Check Status Codes
if (response.status !== 200) {
const error = await response.json();
console.error(`API Error: ${error.error.code} - ${error.error.message}`);
// Handle specific error types
}
2. Implement Retry Logic
Automatically retry on transient errors (5xx, rate limiting) with exponential backoff.
3. Log Request IDs
Always log the request_id from responses for debugging.
4. Validate Input
Validate your request data before sending to reduce 400 errors.
5. Monitor Quotas
Check rate limit headers to proactively avoid hitting limits.