Protected by MagenTrust
    MAGEN
    MAGEN Docs

    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
    CodeMessageTroubleshooting
    UNAUTHORIZEDInvalid or missing API keyVerify X-API-Key header is present and starts with `magen_`
    API_KEY_EXPIREDAPI key has expiredGenerate a new key from your dashboard
    API_KEY_REVOKEDAPI key was revokedContact support or generate a new key

    Validation Errors

    400
    CodeMessageTroubleshooting
    INVALID_SESSION_IDSession ID format invalidEnsure sessionId matches UUID v4 format
    MISSING_ACTIONAction field requiredInclude `action` string in verify-start request
    INVALID_SIGNALSBehavior signals malformedCheck BehaviorSignals schema matches documentation
    SESSION_EXPIREDSession has expiredSessions expire after 5 minutes; start a new one

    Rate Limit Errors

    429
    CodeMessageTroubleshooting
    RATE_LIMIT_EXCEEDEDToo many requestsWait for Retry-After header duration before retrying

    Server Errors

    500
    CodeMessageTroubleshooting
    INTERNAL_ERRORUnexpected server errorRetry with exponential backoff; contact support if persistent
    SERVICE_UNAVAILABLEDownstream service unavailableCheck status.magentrust.ai for incidents

    Session Errors

    404
    CodeMessageTroubleshooting
    SESSION_NOT_FOUNDSession does not existVerify 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}