Error Codes
Complete reference of all API error codes with troubleshooting guidance.
Error Response Structure
All API errors return a consistent JSON structure:
{
"success": false,
"error": "ERROR_CODE",
"message": "Human-readable description",
"request_id": "req_abc123"
}Authentication Errors
401| Code | Message | Troubleshooting |
|---|---|---|
UNAUTHORIZED | Invalid or missing API key | Verify X-API-Key header is present and starts with `magen_` |
API_KEY_EXPIRED | API key has expired | Generate a new key from your dashboard |
API_KEY_REVOKED | API key was revoked | Contact support or generate a new key |
Validation Errors
400| Code | Message | Troubleshooting |
|---|---|---|
INVALID_SESSION_ID | Session ID format invalid | Ensure sessionId matches UUID v4 format |
MISSING_ACTION | Action field required | Include `action` string in verify-start request |
INVALID_SIGNALS | Behavior signals malformed | Check BehaviorSignals schema matches documentation |
SESSION_EXPIRED | Session has expired | Sessions expire after 5 minutes; start a new one |
Rate Limit Errors
429| Code | Message | Troubleshooting |
|---|---|---|
RATE_LIMIT_EXCEEDED | Too many requests | Wait for Retry-After header duration before retrying |
Server Errors
500| Code | Message | Troubleshooting |
|---|---|---|
INTERNAL_ERROR | Unexpected server error | Retry with exponential backoff; contact support if persistent |
SERVICE_UNAVAILABLE | Downstream service unavailable | Check status.magentrust.ai for incidents |
Session Errors
404| Code | Message | Troubleshooting |
|---|---|---|
SESSION_NOT_FOUND | Session does not exist | Verify sessionId; session may have been deleted or never created |
Handling Errors in Code
1async function callMagenAPI(endpoint: string, body: object) {
2 const response = await fetch(`${BASE_URL}${endpoint}`, {
3 method: 'POST',
4 headers: {
5 'Content-Type': 'application/json',
6 'X-API-Key': API_KEY
7 },
8 body: JSON.stringify(body)
9 });
10
11 const data = await response.json();
12
13 if (!response.ok) {
14 switch (data.error) {
15 case 'UNAUTHORIZED':
16 throw new Error('Please check your API key');
17 case 'RATE_LIMIT_EXCEEDED':
18 const retryAfter = response.headers.get('Retry-After');
19 throw new Error(`Rate limited. Retry after ${retryAfter}s`);
20 case 'SESSION_EXPIRED':
21 // Start a new session
22 return await startNewSession();
23 default:
24 throw new Error(data.message || 'Unknown error');
25 }
26 }
27
28 return data;
29}