Ошибки API v3

Все ошибки приходят в одинаковом виде:

{
  "detail": "человекочитаемое описание"
}

Ошибки проверки схемы выглядят подробнее:

{
  "detail": [
    {"loc": ["body", "username"], "msg": "field required", "type": "value_error.missing"}
  ]
}

Коды ответов

Код	Значение	Обычная причина
200	успех	обычное чтение
201	создано	POST создал объект
204	пусто	успешное удаление
400	плохой запрос	кривое тело, неверный формат uuid, неизвестная область доступа
401	не авторизован	ключа нет, он неверен или просрочен
403	запрещено	ключу не хватает области доступа
404	не найдено	объекта не существует
409	конфликт	дубликат имени, одновременное изменение
422	не проходит проверку	схема запроса нарушена
429	слишком часто	превышен лимит, смотрите Retry-After
500	ошибка сервера	наша ошибка, сообщите о ней
502	панель недоступна	не отвечает Remnawave Panel
503	сервис недоступен	нет соединения с базой
504	таймаут	панель не ответила вовремя

Ошибки авторизации

Заголовка нет:

HTTP/1.1 401 Unauthorized

{"detail": "Missing X-API-Key header"}

Ключ не подошёл:

HTTP/1.1 401 Unauthorized

{"detail": "Invalid or expired API key"}

Что проверить: ключ скопирован целиком, вместе с префиксом rwa_; он не выключен в интерфейсе; срок жизни не истёк.

Не хватает прав:

HTTP/1.1 403 Forbidden

{"detail": "Missing scope: users:write"}

Добавьте область доступа ключу или заведите новый с нужным набором.

Лимит запросов

HTTP/1.1 429 Too Many Requests
Retry-After: 17

{"detail": "Rate limit exceeded: 120 requests per minute"}

Окно фиксированное, 60 секунд; Retry-After — сколько секунд до его конца. Клиенту стоит этот заголовок уважать:

import time
import requests

def call(url, headers, max_retries=5):
    for _ in range(max_retries):
        r = requests.get(url, headers=headers)
        if r.status_code != 429:
            return r
        time.sleep(int(r.headers.get("Retry-After", "5")) + 1)
    r.raise_for_status()

Ошибки проверки схемы

HTTP/1.1 422 Unprocessable Entity

{
  "detail": [
    {
      "loc": ["body", "expire_at"],
      "msg": "not a valid datetime",
      "type": "value_error.datetime"
    }
  ]
}

Путь в loc указывает на конкретное поле, которое не прошло.

Ошибки панели

Часть эндпоинтов v3 обращается к API самой панели Remnawave. Если панель тормозит или недоступна, придут 502 или 504. Это временные ошибки — повторяйте запрос с нарастающей паузой.

Как сообщать об ошибке

К 500 полезно приложить:

• время в UTC
• метод и путь запроса
• префикс ключа, первые 12 символов — но не сам ключ
• тело ответа
• значение заголовка X-Request-Id, если он есть

Issues на GitHub.