Начало работы

Ошибки

Ошибки API DonateX: HTTP-статусы, форматы тела ответа и рекомендации по обработке.

Как устроены ошибки

Тип ошибки определяет HTTP-статус, а причина лежит в теле ответа. Формат тела зависит от метода — у каждого метода возможные ошибки и их тексты перечислены в разделе «Ответы».

Простой текст (text/plain) — у большинства методов. Его можно показать пользователю как есть.
{ "error": "..." } — у методов управления алертами и у ответа 429.
ProblemDetails с объектом errors — когда параметр не удалось разобрать (400) и при неверном Content-Type (415).
Пустое тело — у 401 и 403, а также для неизвестного пути и неподдерживаемого HTTP-метода.

400 · text/plain

You can't request more than 100 donations for page

400 · application/json

{
  "error": "Донат не найден"
}

400 · ProblemDetails

{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "take": ["The value 'abc' is not valid."]
  },
  "traceId": "00-28ee8b59243361bcb014e0ee36f90855-c586bb4bb58540c2-00"
}

Статусы

400

Bad Request

Неверные параметры или запрос нельзя выполнить. Причина — в теле ответа.

401

Unauthorized

Токен не передан, истёк, отозван или перевыпущен. Тело пустое.

403

Forbidden

У OAuth-токена нет scope, который нужен методу. Тело пустое.

404

Not Found

Объект не найден — донат, цель, подписка — или такого пути нет в API.

405

Method Not Allowed

Путь существует, но с другим HTTP-методом: например, скип доната — это POST.

409

Conflict

Действие нельзя выполнить в текущем состоянии: например, повторить донат, который ждёт модерации.

415

Unsupported Media Type

Тело запроса отправлено не как JSON. Добавьте Content-Type: application/json.

429

Too Many Requests

Превышен лимит запросов. Сколько секунд подождать — в заголовке Retry-After.

500

Internal Server Error

Непредвиденная ошибка на стороне DonateX. Повторите запрос позже.

Как обрабатывать

4xx — ошибка в запросе: повторять тот же запрос бессмысленно, исправьте параметры или токен.
429 — подождите столько секунд, сколько указано в Retry-After, и повторите.
5xx — временная ошибка: повторите с растущей задержкой.

Обработка ошибок

const response = await fetch(url, { headers });

if (!response.ok) {
  // Тело — строка, { "error": "..." } или ProblemDetails, в зависимости от метода
  const details = await response.text();

  if (response.status === 429) {
    const seconds = Number(response.headers.get('Retry-After') ?? 1);
    await new Promise(resolve => setTimeout(resolve, seconds * 1000));
  } else {
    console.error(response.status, details);
  }
}

Scopes

Дальше

Лимиты