Error Codes and Status Codes

{
  "error": {
    "code": "string",
    "message": "string",
    "details": "string | null",
    "field": "string | null",
    "timestamp": "string (ISO 8601)",
    "requestId": "string",
    "path": "string",
    "traceId": "string | null"
  }
}

{
  "error": {
    "code": "MATIH-COMMON-1000",
    "message": "Validation failed",
    "timestamp": "2026-02-12T10:30:00.000Z",
    "requestId": "req-abc123",
    "path": "/api/v1/tenants",
    "errors": [
      {
        "field": "slug",
        "message": "Slug must be lowercase alphanumeric with hyphens",
        "rejectedValue": "Acme Corp!"
      },
      {
        "field": "adminEmail",
        "message": "Must be a valid email address",
        "rejectedValue": "not-an-email"
      },
      {
        "field": "plan",
        "message": "Must be one of: FREE, STARTER, PROFESSIONAL, ENTERPRISE",
        "rejectedValue": "PLATINUM"
      }
    ]
  }
}

MATIH-{SERVICE}-{NUMBER}

try {
  const response = await apiClient.post('/api/v1/chat', payload);
  return response.data;
} catch (error) {
  if (error.response) {
    const { status, data } = error.response;
    const errorCode = data.error?.code;
 
    switch (status) {
      case 401:
        // Token expired or invalid - attempt refresh
        if (errorCode === 'MATIH-IAM-1001') {
          await refreshToken();
          return retry(request);
        }
        // Other 401s - redirect to login
        redirectToLogin();
        break;
 
      case 403:
        // Insufficient permissions - show access denied
        showAccessDeniedMessage(data.error.message);
        break;
 
      case 429:
        // Rate limited - retry after delay
        const retryAfter = error.response.headers['retry-after'];
        await delay(retryAfter * 1000);
        return retry(request);
 
      case 422:
        // Business logic error - show to user
        showErrorMessage(data.error.message);
        break;
 
      case 502:
      case 503:
      case 504:
        // Upstream error - retry with exponential backoff
        return retryWithBackoff(request, { maxRetries: 3 });
 
      default:
        // Unexpected error - log and show generic message
        logError(data.error);
        showGenericErrorMessage();
    }
  }
}

// Java Spring Boot example
@ExceptionHandler(ResourceNotFoundException.class)
public ResponseEntity<ErrorResponse> handleNotFound(
    ResourceNotFoundException ex, HttpServletRequest request) {
 
    ErrorResponse error = ErrorResponse.builder()
        .code("MATIH-TENANT-2004")
        .message("Tenant not found")
        .details(ex.getMessage())
        .timestamp(Instant.now())
        .requestId(request.getHeader("X-Request-ID"))
        .path(request.getRequestURI())
        .traceId(Span.current().getSpanContext().getTraceId())
        .build();
 
    return ResponseEntity.status(404).body(error);
}

# Python FastAPI example
from fastapi import HTTPException
from datetime import datetime
 
class MatihError(HTTPException):
    def __init__(self, code: str, message: str, status_code: int,
                 details: str = None):
        self.error_code = code
        self.error_message = message
        super().__init__(
            status_code=status_code,
            detail={
                "error": {
                    "code": code,
                    "message": message,
                    "details": details,
                    "timestamp": datetime.utcnow().isoformat() + "Z"
                }
            }
        )
 
# Usage
raise MatihError(
    code="MATIH-AI-2003",
    message="SQL generation failed",
    status_code=422,
    details="Could not generate valid SQL for the given natural language query"
)