API: Ошибки

Документация классов ошибок Kodzero SDK.

KodzeroApiError

Ошибка, возникающая при неуспешных ответах API (4xx, 5xx).

Свойства

Свойство	Тип	Описание
name	'KodzeroApiError'	Имя класса ошибки
message	string	Сообщение об ошибке
url	string	URL запроса
statusCode	number	HTTP код ответа
details	string	Дополнительные детали ошибки

Определение класса

class KodzeroApiError extends Error {
  name: 'KodzeroApiError'
  url: string
  statusCode: number
  details: string

  constructor(
    url: string,
    statusCode: number,
    message: string,
    details?: string
  )
}

Пример обработки

try {
  const user = await User.get('non_existent_id')
} catch (error) {
  if (error.name === 'KodzeroApiError') {
    console.error('URL:', error.url)
    console.error('Код:', error.statusCode)
    console.error('Сообщение:', error.message)
    console.error('Детали:', error.details)
  }
}

Типичные HTTP коды

Код	Описание
400	Неверный запрос
401	Не авторизован
403	Доступ запрещён
404	Не найдено
409	Конфликт (например, дублирующийся email)
422	Ошибка валидации
429	Слишком много запросов
500	Ошибка сервера
503	Сервис недоступен

---

KodzeroValidationError

Ошибка валидации данных.

Свойства

Свойство	Тип	Описание
name	'KodzeroValidationError'	Имя класса ошибки
message	string	Сообщение об ошибке
errors	string[]	Массив ошибок валидации

Определение класса

class KodzeroValidationError extends Error {
  name: 'KodzeroValidationError'
  errors: string[]

  constructor(message: string, errors?: string[])
}

Пример

const user = new User({
  _id: null,
  name: '',
  email: ''
})

const validation = user.validate()

if (!validation.ok) {
  throw new KodzeroValidationError(
    'Ошибка валидации данных',
    validation.errors
  )
}

Обработка

try {
  // ...
} catch (error) {
  if (error.name === 'KodzeroValidationError') {
    console.error('Ошибки:', error.errors)
    // ['name is required', 'email is required']
  }
}

---

Проверка типа ошибки

По имени

try {
  await someOperation()
} catch (error) {
  switch (error.name) {
    case 'KodzeroApiError':
      handleApiError(error)
      break
    case 'KodzeroValidationError':
      handleValidationError(error)
      break
    default:
      handleUnknownError(error)
  }
}

Утилитарные функции

function isKodzeroApiError(error: unknown): error is KodzeroApiError {
  return error instanceof Error && error.name === 'KodzeroApiError'
}

function isKodzeroValidationError(error: unknown): error is KodzeroValidationError {
  return error instanceof Error && error.name === 'KodzeroValidationError'
}

// Использование
try {
  await someOperation()
} catch (error) {
  if (isKodzeroApiError(error)) {
    console.log('API ошибка:', error.statusCode)
  } else if (isKodzeroValidationError(error)) {
    console.log('Ошибки валидации:', error.errors)
  }
}

---

Примеры обработки

Универсальный обработчик

function handleError(error: unknown): {
  type: 'api' | 'validation' | 'unknown'
  message: string
  statusCode?: number
  errors?: string[]
} {
  if (error instanceof Error) {
    if (error.name === 'KodzeroApiError') {
      const apiError = error as any
      return {
        type: 'api',
        message: apiError.message,
        statusCode: apiError.statusCode
      }
    }
    
    if (error.name === 'KodzeroValidationError') {
      const validationError = error as any
      return {
        type: 'validation',
        message: validationError.message,
        errors: validationError.errors
      }
    }
    
    return {
      type: 'unknown',
      message: error.message
    }
  }
  
  return {
    type: 'unknown',
    message: String(error)
  }
}

React компонент для отображения ошибок

interface ErrorDisplayProps {
  error: Error | null
}

function ErrorDisplay({ error }: ErrorDisplayProps) {
  if (!error) return null

  if (error.name === 'KodzeroApiError') {
    const apiError = error as any
    return (
      <div className="error api-error">
        <h4>Ошибка API ({apiError.statusCode})</h4>
        <p>{apiError.message}</p>
        {apiError.details && <small>{apiError.details}</small>}
      </div>
    )
  }

  if (error.name === 'KodzeroValidationError') {
    const validationError = error as any
    return (
      <div className="error validation-error">
        <h4>Ошибки валидации</h4>
        <ul>
          {validationError.errors.map((err: string, i: number) => (
            <li key={i}>{err}</li>
          ))}
        </ul>
      </div>
    )
  }

  return (
    <div className="error unknown-error">
      <p>{error.message}</p>
    </div>
  )
}

Обработка по HTTP коду

async function fetchWithErrorHandling<T>(
  operation: () => Promise<T>
): Promise<T> {
  try {
    return await operation()
  } catch (error) {
    if (error.name === 'KodzeroApiError') {
      const { statusCode, message } = error as any
      
      switch (statusCode) {
        case 401:
          // Перенаправить на логин
          window.location.href = '/login'
          break
        case 403:
          alert('У вас нет доступа к этому ресурсу')
          break
        case 404:
          alert('Запрашиваемый ресурс не найден')
          break
        case 429:
          // Подождать и повторить
          await new Promise(r => setTimeout(r, 5000))
          return fetchWithErrorHandling(operation)
        default:
          alert(`Ошибка: ${message}`)
      }
    }
    throw error
  }
}