Error Handling

Learn how to handle errors gracefully in Magical Auth.

Error Response Format

All errors follow a consistent format:

{
  "code": "VALIDATION_ERROR",
  "message": "Request validation failed",
  "status": 400,
  "request_id": "req_abc123",
  "details": {
    "fields": {
      "phone_number": "Must be a valid E.164 phone number format"
    }
  }
}

Error Codes

Client Errors (4xx)

Error Code	Status	Description
BAD_REQUEST	400	Invalid JSON in request body
VALIDATION_ERROR	400	Request validation failed (see details.fields)
MISSING_PARAMETERS	400	Required parameters missing
SESSION_NOT_FOUND	404	Session expired or not found
CARRIER_NOT_ELIGIBLE	422	Carrier doesn't support Magical Auth
UNSUPPORTED_PLATFORM	422	Browser/platform not supported for the selected strategy
INVALID_CREDENTIAL_FORMAT	422	Invalid credential structure
INVALID_VERIFICATION	422	Authentication response invalid
RATE_LIMIT_EXCEEDED	429	Too many requests

Server Errors (5xx)

Error Code	Status	Description
SERVICE_UNAVAILABLE	503	Carrier service temporarily unavailable
INTERNAL_SERVER_ERROR	500	Unexpected server error

Handling Errors

JavaScript (Web Client SDK)

import { ERROR_CODES } from '@glideidentity/web-client-sdk';

try {
  const result = await client.authenticate({
    use_case: USE_CASE.VERIFY_PHONE_NUMBER,
    phone_number: '+14155551234'
  });
} catch (error) {
  switch (error.code) {
    case ERROR_CODES.CARRIER_NOT_ELIGIBLE:
      // Show SMS fallback
      showSMSVerification();
      break;
    case ERROR_CODES.UNSUPPORTED_PLATFORM:
      // Show browser requirement message
      showBrowserRequirement();
      break;
    case ERROR_CODES.USER_CANCELLED:
      // User closed the prompt
      break;
    default:
      console.error('Error:', error.code, error.message);
  }
}

Node.js (Backend SDK)

import { MagicAuthError } from '@glideidentity/glide-sdk';

try {
  const response = await glide.magicAuth.prepare(request);
} catch (error) {
  if (error instanceof MagicAuthError) {
    console.log('Code:', error.code);
    console.log('Message:', error.message);
    console.log('Status:', error.status);
    console.log('Request ID:', error.requestId);
  }
}

Go (Backend SDK)

response, err := glideClient.MagicAuth.Prepare(ctx, &req)
if err != nil {
    if glideErr, ok := err.(*glide.Error); ok {
        log.Printf("Code: %s, Message: %s, Status: %d", 
            glideErr.Code, glideErr.Message, glideErr.Status)
    }
}

Java (Backend SDK)

try {
    PrepareResponse response = glideClient.magicAuth.prepare(request);
} catch (MagicAuthError e) {
    log.info("Code: {}, Message: {}, Status: {}", 
        e.getCode(), e.getMessage(), e.getStatus());
}

Phone Number Mismatch

When verifying a phone number, a mismatch is not an error. Instead, you'll receive a successful response with verified: false:

{
  "phone_number": "+14155551234",
  "verified": false
}

This allows you to handle mismatches gracefully in your UI.

Best Practices

1. Always provide user-friendly messages - Don't expose raw error codes to users
2. Implement fallbacks - Have SMS/email backup for unsupported carriers
3. Log request IDs - Include request_id in your logs for debugging
4. Handle rate limits - Implement exponential backoff for retries
5. Check platform support - Show browser requirements before starting the flow