Відповіді та помилки

Більшість успішних операцій безпосередньо повертають JSON-об’єкт. Операції зі списками зазвичай мають такий формат:

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

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

Формат помилки

Задокументовані помилки використовують об’єкт із рядком error:

{
  "error": "Human-readable error message"
}

Ваш клієнт має зберігати 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	Перевищено ліміт запитів	Зачекайте й повторіть із випадковою затримкою
5xx	Помилка сервісу або залежності	Повторіть безпечні операції з обмеженим backoff і випадковим відхиленням

Якщо документована операція приймає Idempotency-Key, повторюйте запит із невідомим результатом із тим самим ключем. За явної помилки валідації, автентифікації або cooldown спочатку обробіть її. Коли можливо, прочитайте підсумковий стан ресурсу.

Підтримувані операції й таблицю рішень наведено на сторінці Ідемпотентність і безпечні повтори. Заголовки cooldown скидання описано в розділі Скидання та готовність порту.