Responses and errors

Most successful operations return a JSON object directly. List operations typically use:

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

VPN configuration operations return an archive rather than JSON. Inspect Content-Type before parsing the body.

Error shape

Documented failures use an object with an error string:

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

Your client should preserve the HTTP status, request context, and safe response metadata. Do not log the bearer token or proxy password.

Official SDKs normalize these details into a language-specific API error:

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() ?? '';
}

Retry policy

Status	Meaning	Recommended action
400 / 422	Invalid input	Fix the request; do not retry unchanged
401	Authentication failed	Replace or rotate the token
404	Resource not found	Verify the account-scoped identifier
429	Rate limit exceeded	Back off and retry with jitter
5xx	Service or downstream failure	Retry safe operations with bounded backoff and jitter

For a documented mutation that accepts Idempotency-Key, retry an unknown outcome with the same key. If the API returned a definite validation, authentication, or cooldown error, handle that result before sending another request. Read the resulting resource when possible.

See Idempotency and safe retries for the supported operations and decision table. Reset cooldown headers are explained in Port reset and readiness.