The Masar Eagle API uses standard HTTP status codes and structured error responses to communicate errors. All services implement consistent error handling through the GlobalExceptionMiddleware.
{ "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "Unauthorized access", "status": 401, "detail": "You need to be authenticated to access this resource", "instance": "/api/drivers/me", "errorId": "C3D4E5F6G7H8", "timestamp": "2024-03-10T14:30:00.000Z"}
Invalid Token
{ "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "User not found", "status": 401, "detail": "The authentication token is invalid or has been revoked", "instance": "/api/drivers/me", "errorId": "D4E5F6G7H8I9", "timestamp": "2024-03-10T14:30:00.000Z"}
Expired Token
{ "type": "https://tools.ietf.org/html/rfc7235#section-3.1", "title": "User not found", "status": 401, "detail": "Your session has expired. Please log in again.", "instance": "/api/drivers/me", "errorId": "E5F6G7H8I9J0", "timestamp": "2024-03-10T14:30:00.000Z"}
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.5.3", "title": "User not authorized", "status": 403, "detail": "You do not have permission to access this resource", "instance": "/api/admin/drivers", "errorId": "F6G7H8I9J0K1", "timestamp": "2024-03-10T14:30:00.000Z"}
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "An unexpected error occurred", "status": 500, "detail": "Please try again later or contact support", "instance": "/api/trips", "errorId": "H8I9J0K1L2M3", "timestamp": "2024-03-10T14:30:00.000Z"}
Development Mode Response (includes stack trace):
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.1", "title": "An unexpected error occurred", "status": 500, "detail": "Object reference not set to an instance of an object", "instance": "/api/trips", "errorId": "H8I9J0K1L2M3", "timestamp": "2024-03-10T14:30:00.000Z", "exceptionType": "System.NullReferenceException", "stackTrace": " at TripService.GetTrip(Guid id) in /src/TripService.cs:line 42\n...", "source": "Trips.Api"}
Bad Gateway
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.3", "title": "Service connection error", "status": 502, "detail": "An error occurred while connecting to an external service", "instance": "/api/trips", "errorId": "I9J0K1L2M3N4", "timestamp": "2024-03-10T14:30:00.000Z"}
Gateway Timeout
{ "type": "https://tools.ietf.org/html/rfc7231#section-6.6.5", "title": "Request timeout", "status": 504, "detail": "The request took longer than expected", "instance": "/api/trips", "errorId": "J0K1L2M3N4O5", "timestamp": "2024-03-10T14:30:00.000Z"}
Always log the errorId for 5xx errors to help with troubleshooting:
function logError(error) { if (error.status >= 500 && error.errorId) { // Send to logging service analytics.track('API Error', { errorId: error.errorId, status: error.status, endpoint: error.instance, timestamp: error.timestamp, userId: getCurrentUserId() }); // Show error ID to user for support console.error(`Error ID: ${error.errorId}`); }}
const errorMessages = { 'ar': { 'AUTH_INVALID_CREDENTIALS': 'البريد الإلكتروني أو كلمة المرور غير صحيحة', 'OTP_EXPIRED': 'انتهت صلاحية رمز التحقق. يرجى طلب رمز جديد', 'NF_DRIVER_NOT_FOUND': 'لم يتم العثور على السائق', 'SERVER_ERROR': 'حدث خطأ في الخادم. يرجى المحاولة مرة أخرى' }, 'en': { 'AUTH_INVALID_CREDENTIALS': 'Invalid email or password', 'OTP_EXPIRED': 'OTP code has expired. Please request a new one', 'NF_DRIVER_NOT_FOUND': 'Driver not found', 'SERVER_ERROR': 'A server error occurred. Please try again' }};function showError(errorCode, language = 'ar') { const message = errorMessages[language][errorCode] || errorMessages[language]['SERVER_ERROR']; // Show to user alert(message);}