Error Handling

All API errors include unique identifiers for quick debugging and support.

Error Tracking

Every error generates a unique UUID and is logged to our centralized error-log-service with complete context for debugging.

Error Response Format

All error responses follow this standardized format:

{
  "success": false,
  "status": 403,
  "message": "No access to Mobile App. Missing services: 34, 35",
  "error": "No access to Mobile App. Missing services: 34, 35",
  "errorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "meta": {
    "timestamp": "2025-10-22T12:00:00.000Z",
    "version": "v1",
    "errorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
  }
}

Error UUID

Quick Error Lookup

Use the errorId in support requests for instant error context retrieval. Our team can look up the full error details, stack trace, and request context using this UUID.

What's Included in Error Logs

Each error is stored with:

Service name - Which microservice encountered the error
Operation - The specific operation that failed
Error type - Error class/type
Error message - Human-readable message
Stack trace - Full stack trace (redacted in production)
Request details - Method, path, params, body (sensitive data redacted)
User context - User ID, email, role
Severity - low | medium | high | critical
Timestamp - When the error occurred

Example: Using Error UUID

// API returns error
const response = await fetch('/v1/auth/signin', {
  method: 'POST',
  body: JSON.stringify({ email, password, platform: 'invalid' })
});

const error = await response.json();
console.log('Error ID:', error.errorId);
// a1b2c3d4-e5f6-7890-abcd-ef1234567890

// Contact support with error ID for instant debugging
// Support team can retrieve full error context immediately

HTTP Status Codes

Code	Status	Meaning
200	OK	Request successful
201	Created	Resource created successfully
400	Bad Request	Invalid request data or missing required fields
401	Unauthorized	Missing or invalid authentication
403	Forbidden	Insufficient permissions or platform access
404	Not Found	Resource doesn't exist
409	Conflict	Resource already exists (duplicate)
422	Unprocessable Entity	Validation error
429	Too Many Requests	Rate limit exceeded
500	Internal Server Error	Server error occurred
503	Service Unavailable	Service temporarily unavailable

Error Severity Levels

Errors are automatically classified by severity:

Severity	Status Codes	Description
Critical	500-599	Server errors requiring immediate attention
High	Manual	Business-critical errors
Medium	400-499	Client errors, validation failures
Low	300-399	Warnings, redirects

Common Errors

Authentication Errors

{
  "success": false,
  "status": 400,
  "message": "Platform is required. Valid options: app, live-platform, backoffice",
  "errorId": "uuid-here",
  "meta": {
    "errorId": "uuid-here"
  }
}

Solution: Include platform parameter in sign-in/sign-up requests.

{
  "success": false,
  "status": 401,
  "message": "External Backoffice authentication failed",
  "errorId": "uuid-here",
  "meta": {
    "errorId": "uuid-here"
  }
}

Solution: Verify email and password are correct.

{
  "success": false,
  "status": 403,
  "message": "No access to Mobile App. Missing services: 34, 35",
  "errorId": "uuid-here",
  "meta": {
    "errorId": "uuid-here"
  }
}

Solution: User doesn't have required service IDs. Contact administrator to add services.

Validation Errors

{
  "success": false,
  "status": 422,
  "message": "Validation failed",
  "errors": [
    {
      "field": "email",
      "message": "Invalid email format"
    },
    {
      "field": "password",
      "message": "Password must be at least 8 characters"
    }
  ],
  "errorId": "uuid-here",
  "meta": {
    "errorId": "uuid-here"
  }
}

Sensitive Data Protection

Automatic Sanitization

All error logs automatically redact sensitive data including passwords, tokens, API keys, and authorization headers.

Redacted Fields:

password
token, accessToken, refreshToken
apiKey, secret, clientSecret
authorization header
x-api-key header
cookie header

Error Handling Best Practices

1. Always Check for Error UUID

if (!response.ok) {
  const error = await response.json();
  console.error(`Error ${error.errorId}: ${error.message}`);
  // Include errorId in bug reports
}

2. Handle Platform Errors

try {
  const response = await signIn(email, password, platform);
} catch (error) {
  if (error.status === 403 && error.message.includes('Missing services')) {
    // User doesn't have platform access
    showMessage('Please contact support to activate platform access');
  }
}

3. Implement Retry Logic

async function signInWithRetry(email, password, platform, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await signIn(email, password, platform);
    } catch (error) {
      if (error.status >= 500 && i < maxRetries - 1) {
        // Retry on server errors
        await sleep(1000 * (i + 1));
        continue;
      }
      throw error;
    }
  }
}

4. Log Error UUIDs

window.addEventListener('unhandledrejection', (event) => {
  const errorId = event.reason?.errorId;
  if (errorId) {
    // Send to your error tracking service
    trackError({ errorId, context: 'unhandled_rejection' });
  }
});

Error Lookup

Support teams can retrieve full error details using the UUID:

GET /v1/errors/{errorId}
X-API-Key: admin-api-key

Response:
{
  "errorId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "serviceName": "auth-service",
  "operation": "POST /auth/signin",
  "errorMessage": "No access to Mobile App",
  "request": {
    "method": "POST",
    "path": "/auth/signin",
    "body": { "email": "...", "password": "[REDACTED]" }
  },
  "user": {
    "userId": "user_123",
    "email": "user@example.com"
  },
  "severity": "medium",
  "timestamp": "2025-10-22T12:00:00.000Z"
}

Rate Limiting Errors

{
  "success": false,
  "status": 429,
  "message": "Rate limit exceeded. Please wait.",
  "error": "Rate limit exceeded",
  "errorId": "uuid-here",
  "meta": {
    "retryAfter": 60,  // Seconds to wait
    "errorId": "uuid-here"
  }
}

Response Headers:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1698765432
Retry-After: 60

Error Handling

On this page