Ошибки

Когда что-то идёт не так, API возвращает JSON-объект с описанием ошибки и соответствующим HTTP-статусом.

Формат ошибки

{
  "error": {
    "code": 400,
    "type": "bad_request",
    "message": "invalid request body",
    "fields": [
      {
        "field": "phone",
        "message": "phone is required"
      }
    ]
  }
}

Поле	Описание
code	HTTP-статус код
type	Тип ошибки (строка)
message	Читаемое описание ошибки
fields	Список ошибок валидации (только для 400)

HTTP-статусы

Статус	Когда возникает
400 Bad Request	Неверный формат запроса, невалидные поля
401 Unauthorized	Ключ не передан, неверный или отключён
403 Forbidden	Ключ не имеет нужного разрешения
404 Not Found	Ресурс не найден (SMS, устройство)
409 Conflict	Конфликт — например, устройство уже существует
422 Unprocessable	Логическая ошибка — например, устройство офлайн
429 Too Many Requests	Превышен лимит запросов
500 Internal Server Error	Внутренняя ошибка сервера

Примеры ошибок

Ключ не передан — 401

{
  "error": {
    "code": 401,
    "type": "unauthorized",
    "message": "api key is required: use Authorization: Bearer <key> header or ?token= query param"
  }
}

Нет разрешения — 403

{
  "error": {
    "code": 403,
    "type": "forbidden",
    "message": "insufficient permissions"
  }
}

Ошибка валидации — 400

{
  "error": {
    "code": 400,
    "type": "validation_error",
    "message": "validation failed",
    "fields": [
      {
        "field": "phone",
        "message": "phone must be a valid phone number"
      },
      {
        "field": "message",
        "message": "message is required"
      }
    ]
  }
}

Ресурс не найден — 404

{
  "error": {
    "code": 404,
    "type": "not_found",
    "message": "sms not found"
  }
}

Советы по обработке ошибок

async function apiRequest(url, options) {
  const response = await fetch(url, options);

  if (!response.ok) {
    const body = await response.json();
    const err = body.error;

    // Ошибки валидации — показываем пользователю детали
    if (err.code === 400 && err.fields) {
      const details = err.fields.map(f => `${f.field}: ${f.message}`).join('\n');
      throw new Error(`Ошибка валидации:\n${details}`);
    }

    // Авторизация — перенаправляем на страницу с ключами
    if (err.code === 401 || err.code === 403) {
      throw new Error('Проверьте API-ключ и его разрешения');
    }

    throw new Error(err.message);
  }

  // 204 No Content — тело ответа пустое
  if (response.status === 204) return null;

  return response.json();
}