Ответы и ошибки

Большинство успешных операций возвращают JSON-объект напрямую. Списки обычно имеют форму:

{
  "data": [],
  "page": 1,
  "pageSize": 20,
  "total": 0
}

Операции VPN-конфигурации возвращают архив, а не JSON. Проверяйте Content-Type до разбора тела.

Форма ошибки

Документированные ошибки представлены объектом со строкой error:

{
  "error": "Читаемое описание ошибки"
}

Сохраняйте HTTP-статус, контекст запроса и безопасные метаданные ответа. Не записывайте bearer-токен или пароль прокси в лог.

Официальные SDK преобразуют эти данные в специальную ошибку API для языка клиента:

JavaScript

import { ApiError } from '@ltesocks/sdk';

try {
  await client.ports.get({ id: '10000' });
} catch (error) {
  if (error instanceof ApiError) {
    console.error(error.statusCode, error.kind, error.detail);
    console.error(error.retryAfter, error.retryAt);
  }
}

Python

from ltesocks_sdk import ApiError

try:
    client.ports.get("10000")
except ApiError as error:
    print(error.status_code, error.kind, error.detail)
    print(error.retry_after, error.retry_at)

PHP

<?php

use LTESocks\ApiException;

try {
    $client->ports()->get('10000');
} catch (ApiException $error) {
    echo $error->getStatusCode();
    echo $error->getRetryAt() ?? '';
}

Стратегия повторов

Статус	Значение	Действие
400 / 422	Неверные данные	Исправить запрос, не повторять без изменений
401	Ошибка авторизации	Заменить или ротировать токен
404	Ресурс не найден	Проверить идентификатор в рамках аккаунта
429	Превышен лимит	Подождать и повторить с jitter
5xx	Ошибка сервиса	Ограниченно повторять безопасные операции с backoff и jitter

Если документированная операция принимает Idempotency-Key, повторяйте запрос с неизвестным результатом с тем же ключом. При явной ошибке валидации, авторизации или cooldown сначала обработайте ее. Когда возможно, прочитайте итоговое состояние ресурса.

Поддерживаемые операции и таблица решений приведены на странице Идемпотентность и безопасные повторы. Заголовки cooldown сброса описаны в разделе Сброс и готовность порта.