Customer API Documentation

Getting started

1. 1. The production My API page links to sandbox integration testing. Sign in to the customer portal in the test environment, open My API, and create an App ID with the prefix sbx_app_ . Save the API Secret immediately.
2. 2. Store PUPPYIP_API_BASE_URL, PUPPYIP_API_APP_ID and PUPPYIP_API_SECRET in server-side environment variables, not frontend pages.
3. 3. First call GET /api/v1/account to verify signing, then call GET /api/v1/offers to retrieve available products.
4. 4. When creating an order or renewal, generate one Idempotency-Key for each business operation. Timeout or network retries of that same operation must reuse the original key and exactly the same raw body. Change the key only for a new business operation.
5. 5. Successful order creation means the order has been accepted. Save the returned order_no and check order details at the interval specified by poll_after_seconds until the order is completed or refunded.
6. 6. Set a stable User-Agent for server-side requests, such as PuppyIP-Integration/1.0, to avoid security policies misidentifying default script identifiers.
7. 7. After sandbox testing, return to production and create an App ID with the prefix live_app_ . For launch, replace only the production environment variables. After copying the examples, only the environment variables need changing; do not rewrite signing functions, headers or endpoint paths.

Storefront integration

Connect your website to PuppyIP to browse products, purchase, deliver and renew proxies. Your application manages its own customers, retail prices, payments, ledger and support.

Map customers to their orders

Your API key represents your PuppyIP account. The account, wallet, orders and proxies endpoints return that account’s data. Store a mapping from your customer to your local order, order_no and proxy_id on your server. Check ownership before displaying or managing a resource. Never expose your entire API account’s orders or proxy list to each customer.

The note field is an order annotation, not an access control or search filter. Current responses do not return it. Keep the API Secret and connection credentials out of public pages and logs.

1. Display products

   GET /api/v1/offers

   Use /offers/available for available products, or /offers for the product list. Read every page and update products by offer_code. Request include=cidr_stock,line_group for per-range stock and Standard/Recommended categories.

2. Check price and stock

   GET /api/v1/offers

   Request a quote for the selected quantity and duration. Manage your retail price separately. For a selected CIDR, check both cidr_stock and max_quantity: 0 means unavailable and null means unknown. Queries do not lock prices or reserve stock.

3. Payments and balance

   GET /api/v1/wallet

   Customers pay your website; API purchases and renewals debit your PuppyIP wallet. Reconcile the two ledgers separately. The API does not collect payment from your customers or add funds for you.

4. Create an order

   POST /api/v1/orders

   Save your local order, Idempotency-Key and exact JSON bytes before submitting. Retry a timeout with the same key and body but a fresh signature. Save order_no after HTTP 201; acceptance does not mean delivery is complete.

5. Deliver proxies

   GET /api/v1/orders/{order_no}

   Poll at poll_after_seconds and respect Retry-After on HTTP 429. Deliver only connections allowed by delivery.available. With partial delivery enabled, also check complete and remaining_count.

6. Refresh connections

   GET /api/v1/proxies/{proxy_id}

   Save proxy_id and retrieve its latest host, port, credentials and expiry to update your records. When webhook delivery is enabled, verify each notification and query current state; otherwise keep polling. The API does not update connection settings in your customers’ software.

7. Renew and reconcile

   POST /api/v1/proxies/renew

   Select proxy_ids belonging to your local customer. Check successful, failed and unresolved items separately. Do not create another renewal for unresolved items. Refund fields describe the PuppyIP transaction; they do not mean you have refunded your own customer.

API v1 does not register sub-customers, collect their payments, add funds, accept refund requests, replace IPs or supply trial IPs. Manage your customer workflows in your own application. Credential updates require separate permission and an environment where the operation is enabled.

Switching environments

Store connection details in environment variables. For testing, use PUPPYIP_API_BASE_URL=https://sandbox.puppyip.com and an App ID beginning with sbx_app_ ; for production, switch to PUPPYIP_API_BASE_URL=https://puppyip.com and an App ID beginning with live_app_ . Headers, signing functions and endpoint paths do not change between testing and production.

PUPPYIP_API_BASE_URL=https://sandbox.puppyip.com
PUPPYIP_API_APP_ID=sbx_app_EXAMPLE_SANDBOX_APP_ID
PUPPYIP_API_SECRET=replace-with-your-secret

Available endpoints

Request headers

Canonical String

Before signing, split the request into 7 lines and join them with the newline character \n :

METHOD
host
path
canonical_query
timestamp
nonce
sha256(body)

Fixed GET /api/v1/account example

GET
puppyip.com
/api/v1/account

2026-06-28T12:00:00+00:00
nonce-empty-body
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

The fixed example above uses the documentation test Secret puppyip-docs-test-secret and produces this signature: e3c27a2055ad38f16861790294802b9fac81e02e8d72fbeaa87299598785832d.

Code examples

These examples use environment variables. Do not put your API Secret in frontend pages, public repositories or logs.

curl

curl only sends the request. First use the PHP or Node.js signing function below to generate the current TIMESTAMP, NONCE and SIGNATURE for this request. Do not send requests using the fixed algorithm-check values above, and do not write your Secret into shell history.

curl "$PUPPYIP_API_BASE_URL/api/v1/account" \
  -H "X-API-AppId: $PUPPYIP_API_APP_ID" \
  -H "X-API-Timestamp: $TIMESTAMP" \
  -H "X-API-Nonce: $NONCE" \
  -H "X-API-Signature: $SIGNATURE" \
  -H "Accept: application/json" \
  -H "User-Agent: PuppyIP-Integration/1.0"

PHP

$baseUrl = rtrim(getenv('PUPPYIP_API_BASE_URL') ?: 'https://sandbox.puppyip.com', '/');
$appId = getenv('PUPPYIP_API_APP_ID') ?: '';
$secret = getenv('PUPPYIP_API_SECRET') ?: '';
$method = 'GET';
$target = $baseUrl.'/api/v1/account';
$parts = parse_url($target);
$path = $parts['path'] ?? '/';
$rawQuery = $parts['query'] ?? '';
$body = '';
$timestamp = gmdate('Y-m-d\TH:i:s\Z');
$nonce = 'nce_'.bin2hex(random_bytes(16));
$host = strtolower($parts['host'] ?? '');

function canonicalQuery(string $rawQuery): string
{
    if ($rawQuery === '') {
        return '';
    }

    $pairs = array_map(function (string $pair): array {
        [$key, $value] = array_pad(explode('=', $pair, 2), 2, '');

        return [rawurlencode(rawurldecode($key)), rawurlencode(rawurldecode($value))];
    }, explode('&', $rawQuery));

    usort($pairs, fn (array $left, array $right): int => $left[0] <=> $right[0] ?: $left[1] <=> $right[1]);

    return implode('&', array_map(fn (array $pair): string => $pair[0].'='.$pair[1], $pairs));
}

$canonical = implode("\n", [
    $method,
    $host,
    $path,
    canonicalQuery($rawQuery),
    $timestamp,
    $nonce,
    hash('sha256', $body),
]);

$signature = hash_hmac('sha256', $canonical, $secret);
$headers = [
    'X-API-AppId: '.$appId,
    'X-API-Timestamp: '.$timestamp,
    'X-API-Nonce: '.$nonce,
    'X-API-Signature: '.$signature,
    'Accept: application/json',
    'User-Agent: PuppyIP-Integration/1.0',
];

$handle = curl_init($target);
curl_setopt_array($handle, [
    CURLOPT_RETURNTRANSFER => true,
    CURLOPT_HTTPHEADER => $headers,
]);
$response = curl_exec($handle);

if ($response === false) {
    throw new RuntimeException(curl_error($handle));
}

echo $response;

Node.js

import crypto from 'node:crypto';

const baseUrl = process.env.PUPPYIP_API_BASE_URL ?? 'https://sandbox.puppyip.com';
const appId = process.env.PUPPYIP_API_APP_ID ?? '';
const secret = process.env.PUPPYIP_API_SECRET ?? '';
const method = 'GET';
const url = new URL('/api/v1/account', baseUrl);
const body = '';
const timestamp = new Date().toISOString().replace(/\.\d{3}Z$/, 'Z');
const nonce = `nce_${crypto.randomBytes(16).toString('hex')}`;

const rfc3986 = (value) => encodeURIComponent(value).replace(
  /[!'()*]/g,
  (character) => `%${character.charCodeAt(0).toString(16).toUpperCase()}`,
);
const compare = (left, right) => left < right ? -1 : (left > right ? 1 : 0);
const canonicalQuery = (rawQuery) => {
  if (rawQuery === '') return '';

  return rawQuery
    .split('&')
    .map((pair) => {
      const separator = pair.indexOf('=');
      const key = separator === -1 ? pair : pair.slice(0, separator);
      const value = separator === -1 ? '' : pair.slice(separator + 1);

      return [rfc3986(decodeURIComponent(key)), rfc3986(decodeURIComponent(value))];
    })
    .sort((left, right) => compare(left[0], right[0]) || compare(left[1], right[1]))
    .map(([key, value]) => `${key}=${value}`)
    .join('&');
};
const rawQuery = url.search.startsWith('?') ? url.search.slice(1) : url.search;

const canonical = [
  method,
  url.hostname.toLowerCase(),
  url.pathname,
  canonicalQuery(rawQuery),
  timestamp,
  nonce,
  crypto.createHash('sha256').update(body).digest('hex'),
].join('\n');

const signature = crypto
  .createHmac('sha256', secret)
  .update(canonical)
  .digest('hex');

const headers = {
  'X-API-AppId': appId,
  'X-API-Timestamp': timestamp,
  'X-API-Nonce': nonce,
  'X-API-Signature': signature,
  Accept: 'application/json',
  'User-Agent': 'PuppyIP-Integration/1.0',
};

const response = await fetch(url, { method, headers });
console.log(await response.json());

Response envelope

All endpoints return a consistent JSON envelope. On success, success=true and the business data is in data. On failure, code is the stable error code, and trace_id helps support investigate the request.

{
  "success": true,
  "code": "ok",
  "message": "OK",
  "data": {},
  "timestamp": "2026-06-28T12:00:00+00:00",
  "trace_id": "trc_EXAMPLE_TRACE_ID"
}

Get account

Check the account associated with your API key.

Required scopeaccount:read

Request parameters

No additional business parameters. Signed request headers are still required.

• Every operation is scoped to the account owning the key. IP replacement and trial IPs are not available through this API.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/account

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "account_id": "acct_0123456789abcdef0123456789",
        "email": "[email protected]",
        "email_verified": true,
        "status": "active",
        "created_at": "2026-11-09T00:00:00+00:00"
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get wallet balance

Check the balance and currency used for API purchases.

Required scopewallet:read

Request parameters

No additional business parameters. Signed request headers are still required.

• Use the returned currency and integer amounts for balance checks. This API does not provide an add-funds operation; sandbox funds have no cash value.
• Calculate money with integer minor units or exact decimal arithmetic, not binary floating point. Decimal amount fields are strings with two places.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/wallet

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "currency": "CNY",
        "balance_cents": 10000,
        "balance": "100.00",
        "frozen_cents": 0,
        "cash_value": true
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Browse products

Find available products, prices, durations and IP ranges before ordering.

Required scopeoffers:read

Request parameters

• Quotes use your account pricing, requested quantity and duration; they do not reserve stock. Prices and stock can change before purchase. Do not add stock counts from different products together. A stock value of null means unknown, not zero or unlimited.
• Calculate money with integer minor units or exact decimal arithmetic, not binary floating point. Decimal amount fields are strings with two places.
• Pass next_page_token back unchanged and keep the same filters and delivery mode. Tokens expire after 3 days. Continue while has_more is true, even after an empty page. Pages are not a frozen snapshot.
• The sandbox includes Standard, Recommended and CIDR test products, with per-range stock values of 3, 0 and null. null means unknown, not zero or total stock. Quantity limits apply per request; global stock depletion is not simulated. Returned connections are for testing and do not represent real exits in the selected range.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/offers?page_size=200

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "currency": "CNY",
        "payment_mode": "wallet",
        "offers": [
            {
                "offer_code": "off_0123456789abcdef0123456789",
                "name": "United States - Los Angeles",
                "country_code": "US",
                "country_name": "United States",
                "region": "Los Angeles",
                "line_name": "United States - Los Angeles",
                "ip_type": "2",
                "protocol": "0",
                "unit_price_cents": 2000,
                "unit_price": "20.00",
                "base_duration_days": 30,
                "duration_days": [
                    30,
                    60,
                    90
                ],
                "max_quantity": 12,
                "cidrs": [
                    "198.51.100.0/24"
                ]
            }
        ],
        "page_size": 200,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

GET /api/v1/offers?line_group=recommended&include=cidr_stock,line_group&page_size=200

{
  "offer_code": "offer-code-from-response",
  "line_group": "recommended",
  "ip_type": "2",
  "protocol": "0",
  "max_quantity": 20,
  "cidrs": ["198.51.100.0/24", "203.0.113.0/24", "192.0.2.0/24"],
  "cidr_stock": {
    "198.51.100.0/24": 12,
    "203.0.113.0/24": 0,
    "192.0.2.0/24": null
  },
  "stock_updated_at": "2026-11-09T08:00:00+00:00"
}

Create an order

Buy one or more products using your wallet, then check the order for delivery.

Required scopeorders:write

Request parameters

• HTTP 201 confirms order creation, not completed delivery. Save order_no and follow poll_after_seconds. For one product, do not repeat a CIDR or mix automatic allocation with specified CIDRs in the same request.
• Calculate money with integer minor units or exact decimal arithmetic, not binary floating point. Decimal amount fields are strings with two places.
• After a timeout, retry with the original Idempotency-Key and identical body bytes, using a fresh timestamp and nonce. Never change the key merely because the result is still pending.
• external_order_no is unique within your account and environment. Reusing it with the identical raw request body returns the original creation result without another charge; a different body returns 409 external_order_conflict. Reads add it only with include=external_order_no.
• Sandbox final_partial requires at least 2 IPs: some are delivered and confirmed failures are refunded, ending as delivered with payment_status=partially_refunded. indeterminate remains procurement_blocked without delivery, automatic refund or repeated execution. The existing partial scenario still delivers some IPs first and completes later.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

POST /api/v1/orders
Content-Type: application/json
Idempotency-Key: example-create-order-001

{
    "offer_code": "off_0123456789abcdef0123456789",
    "quantity": 1,
    "duration_days": 30
}

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 201

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "order_no": "PSO20261109000000EXAMPLE",
        "status": "procuring",
        "payment_status": "paid",
        "payment_method": "wallet",
        "currency": "CNY",
        "subtotal_cents": 2000,
        "total_cents": 2000,
        "total": "20.00",
        "created_at": "2026-11-09T00:00:00+00:00",
        "items": [
            {
                "name": "United States - Los Angeles",
                "quantity": 1,
                "duration_days": 30,
                "offer_code": "off_0123456789abcdef0123456789",
                "unit_price_cents": 2000,
                "total_price_cents": 2000
            }
        ],
        "delivery": {
            "expected_count": 1,
            "delivered_count": 0,
            "complete": false,
            "available": false
        },
        "poll_after_seconds": 1,
        "refund": null,
        "proxies": []
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

POST /api/v1/orders
Idempotency-Key: order-demo-001

{
  "duration_days": 30,
  "items": [
    {"offer_code": "sandbox_us_static", "quantity": 2},
    {"offer_code": "sandbox_jp_static", "quantity": 1}
  ]
}

POST /api/v1/orders
Idempotency-Key: order-note-demo-001

{
  "offer_code": "sandbox_us_static",
  "quantity": 2,
  "duration_days": 30,
  "note": "客户A / 业务单号12345"
}

List orders

Browse your account’s order history, including orders placed on the website.

Required scopeorders:read

Request parameters

• The list returns summaries without connection credentials or item prices. Status follows the current delivery mode. Continue paging while has_more=true, even when a page is empty.
• Partial delivery is optional on GET requests only. Without the header, the existing delivery behavior and response fields remain unchanged.
• Pass next_page_token back unchanged and keep the same filters and delivery mode. Tokens expire after 3 days. Continue while has_more is true, even after an empty page. Pages are not a frozen snapshot.
• Filters are combined. Repeat equivalent filters and delivery mode on later pages; changing or removing them returns invalid_page_token. Date ranges include both endpoints.
• external_order_no is unique within your account and environment. Reusing it with the identical raw request body returns the original creation result without another charge; a different body returns 409 external_order_conflict. Reads add it only with include=external_order_no.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/orders?page_size=50

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "orders": [
            {
                "order_no": "PSO20261109000000EXAMPLE",
                "status": "delivered",
                "payment_status": "paid",
                "payment_method": "wallet",
                "currency": "CNY",
                "total_cents": 2000,
                "total": "20.00",
                "created_at": "2026-11-09T00:00:00+00:00",
                "items": [
                    {
                        "name": "United States - Los Angeles",
                        "quantity": 1,
                        "duration_days": 30,
                        "offer_code": "off_0123456789abcdef0123456789"
                    }
                ],
                "delivery": {
                    "expected_count": 1,
                    "delivered_count": 1,
                    "complete": true,
                    "available": true
                },
                "poll_after_seconds": null,
                "refund": null
            }
        ],
        "page_size": 50,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get order details

Check payment, delivery and refund progress, and retrieve available connections.

Required scopeorders:read

Request parameters

• Use delivery.available to decide whether connections are readable. Check refund.currency and refund.amount_cents independently of the order total; an unknown refund amount is not zero.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.
• Partial delivery is optional on GET requests only. Without the header, the existing delivery behavior and response fields remain unchanged.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/orders/PSO20261109000000EXAMPLE

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "order_no": "PSO20261109000000EXAMPLE",
        "status": "delivered",
        "payment_status": "paid",
        "payment_method": "wallet",
        "currency": "CNY",
        "subtotal_cents": 2000,
        "total_cents": 2000,
        "total": "20.00",
        "created_at": "2026-11-09T00:00:00+00:00",
        "items": [
            {
                "name": "United States - Los Angeles",
                "quantity": 1,
                "duration_days": 30,
                "offer_code": "off_0123456789abcdef0123456789",
                "unit_price_cents": 2000,
                "total_price_cents": 2000
            }
        ],
        "delivery": {
            "expected_count": 1,
            "delivered_count": 1,
            "complete": true,
            "available": true
        },
        "poll_after_seconds": null,
        "refund": null,
        "proxies": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "status": "active",
                "host": "198.51.100.10",
                "port": 10080,
                "protocol": "0",
                "username": "example_user",
                "password": "example_password",
                "connection": "198.51.100.10:10080:example_user:example_password",
                "socks5_uri": "socks5://example_user:[email protected]:10080",
                "ip_type": "2",
                "country_code": "US",
                "region": "Los Angeles",
                "line_name": "US Los Angeles 2",
                "starts_at": "2026-11-09T00:00:00+00:00",
                "expires_at": "2026-12-09T00:00:00+00:00"
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Order details include order_no, status, payment_status, payment_method, currency, subtotal_cents, total_cents, total, created_at, items, delivery, poll_after_seconds, refund and proxies. Lists return only safe summaries without proxy credentials. refund is null or a refund-status object containing status, destination, amount_cents, currency and refunded_at. refund.status=succeeded confirms the recorded refund, not a full refund of the order; check payment_status for that. An unconfirmed amount, currency or destination is null, which does not mean zero or no refund. Read amount_cents with its own currency; do not infer it from the order currency or current exchange rates.

Order states and sandbox scenarios

List proxies

Retrieve your available proxy connections in pages.

Required scopeproxies:read

Request parameters

• Use explicit pagination for new integrations. Omitting both pagination parameters in production keeps the legacy limit of 2000 records, not an unlimited list. Filters do not change ownership or expiry-retention rules.
• The production proxy list retains expired resources for 72 hours after expires_at; resources with a null expiry also remain eligible. This list rule does not impose the same limit on the single-proxy endpoint or sandbox list.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.
• Partial delivery is optional on GET requests only. Without the header, the existing delivery behavior and response fields remain unchanged.
• Pass next_page_token back unchanged and keep the same filters and delivery mode. Tokens expire after 3 days. Continue while has_more is true, even after an empty page. Pages are not a frozen snapshot.
• Filters are combined. Repeat equivalent filters and delivery mode on later pages; changing or removing them returns invalid_page_token. Date ranges include both endpoints.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/proxies?page_size=100

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "proxies": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "status": "active",
                "host": "198.51.100.10",
                "port": 10080,
                "protocol": "0",
                "username": "example_user",
                "password": "example_password",
                "connection": "198.51.100.10:10080:example_user:example_password",
                "socks5_uri": "socks5://example_user:[email protected]:10080",
                "ip_type": "2",
                "country_code": "US",
                "region": "Los Angeles",
                "line_name": "US Los Angeles 2",
                "starts_at": "2026-11-09T00:00:00+00:00",
                "expires_at": "2026-12-09T00:00:00+00:00"
            }
        ],
        "page_size": 100,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get a proxy

Retrieve the latest connection details for a saved proxy ID.

Required scopeproxies:read

Request parameters

• Keep proxy_id as your resource key and refresh its connection details when needed. This endpoint returns the proxy object directly inside data, without an environment wrapper.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.
• Partial delivery is optional on GET requests only. Without the header, the existing delivery behavior and response fields remain unchanged.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/proxies/px_0123456789abcdef0123456789

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "proxy_id": "px_0123456789abcdef0123456789",
        "status": "active",
        "host": "198.51.100.10",
        "port": 10080,
        "protocol": "0",
        "username": "example_user",
        "password": "example_password",
        "connection": "198.51.100.10:10080:example_user:example_password",
        "socks5_uri": "socks5://example_user:[email protected]:10080",
        "ip_type": "2",
        "country_code": "US",
        "region": "Los Angeles",
        "line_name": "US Los Angeles 2",
        "starts_at": "2026-11-09T00:00:00+00:00",
        "expires_at": "2026-12-09T00:00:00+00:00"
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Renew proxies

Extend selected proxies using your wallet and check each proxy’s result.

Required scopeproxies:write

Request parameters

• HTTP 200 does not mean every proxy renewed. Check all three ID lists and line_items. A full failure returns HTTP 422 with the same result structure in data. Unresolved units require reconciliation; do not create another renewal for them.
• Calculate money with integer minor units or exact decimal arithmetic, not binary floating point. Decimal amount fields are strings with two places.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.
• After a timeout, retry with the original Idempotency-Key and identical body bytes, using a fresh timestamp and nonce. Never change the key merely because the result is still pending.
• Only successful sandbox items gain time. Confirmed failures are refunded; unknown items remain charged and are not automatically renewed again. failed returns HTTP 422 operation_failed with the result in data; other scenarios return 200. The same key replays the original result, and unresolved proxies reject a new renewal.
• Omitting sync, or setting true, preserves the existing synchronous result. With sync=false, supply distinct proxy_ids. A new operation returns HTTP 202 with data={"operation_id":"rop_...","status":"processing"}; this is not a successful renewal. Poll GET /api/v1/proxies/renewal-operations/{operation_id}. Retrying the original key/body can replay the original acceptance, so query the operation for progress. Production requires asynchronous renewal to be enabled; sandbox uses isolated simulations.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

POST /api/v1/proxies/renew
Content-Type: application/json
Idempotency-Key: example-renew-001

{
    "proxy_ids": [
        "px_0123456789abcdef0123456789"
    ],
    "duration_days": 30
}

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "status": "completed",
        "currency": "CNY",
        "total_cents": 2000,
        "total": "20.00",
        "charged_cents": 2000,
        "refunded_cents": 0,
        "successful_proxy_ids": [
            "px_0123456789abcdef0123456789"
        ],
        "failed_proxy_ids": [],
        "unresolved_proxy_ids": [],
        "line_items": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "host": "198.51.100.10",
                "status": "succeeded",
                "duration_days": 30,
                "amount_cents": 2000,
                "amount": "20.00",
                "charged_cents": 2000,
                "refunded_cents": 0
            }
        ],
        "proxies": [
            {
                "proxy_id": "px_0123456789abcdef0123456789",
                "status": "active",
                "host": "198.51.100.10",
                "port": 10080,
                "protocol": "0",
                "username": "example_user",
                "password": "example_password",
                "connection": "198.51.100.10:10080:example_user:example_password",
                "socks5_uri": "socks5://example_user:[email protected]:10080",
                "ip_type": "2",
                "country_code": "US",
                "region": "Los Angeles",
                "line_name": "US Los Angeles 2",
                "starts_at": "2026-11-09T00:00:00+00:00",
                "expires_at": "2027-01-08T00:00:00+00:00"
            }
        ],
        "wallet": {
            "environment": "production",
            "currency": "CNY",
            "balance_cents": 8000,
            "balance": "80.00",
            "frozen_cents": 0,
            "cash_value": true
        }
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

POST requests use application/json. Renewal proxy_ids must be a nonempty array of public IDs, with up to 1000 IDs per request. Each ID is limited to 80 characters. Exceeding these limits returns HTTP 422 / validation_error. duration_days must be a positive multiple of 30 and no greater than 1095. Pagination tokens are opaque strings. Responses contain optional fields; clients should tolerate new fields. For unknown business states, stop automatic retries, retain trace_id and contact support.

POST /api/v1/proxies/renew
Idempotency-Key: renew-demo-001

{
  "proxy_ids": ["SANDBOX_PROXY_20260629080000_001"],
  "duration_days": 30
}

{
  "status": "completed",
  "total_cents": 12000,
  "charged_cents": 12000,
  "refunded_cents": 0,
  "successful_proxy_ids": ["SANDBOX_PROXY_20260629080000_001"],
  "failed_proxy_ids": [],
  "unresolved_proxy_ids": [],
  "line_items": [{
    "proxy_id": "SANDBOX_PROXY_20260629080000_001",
    "host": "198.51.100.10",
    "status": "succeeded",
    "duration_days": 30,
    "amount_cents": 12000,
    "amount": "120.00",
    "charged_cents": 12000,
    "refunded_cents": 0
  }]
}

List locations

Get public location identifiers from the current catalog.

Required scopeoffers:read

Request parameters

No additional business parameters. Signed request headers are still required.

• Directories support filtering, not a guarantee of stock for a quantity or duration. Check product quotes and availability, then order with offer_code.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/locations

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "locations": [
            {
                "location_id": "loc_0123456789abcdef0123456789ab",
                "country_code": "US",
                "country_name": "United States",
                "region": "Los Angeles"
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get the location tree

Browse catalog locations grouped by country.

Required scopeoffers:read

Request parameters

No additional business parameters. Signed request headers are still required.

• Directories support filtering, not a guarantee of stock for a quantity or duration. Check product quotes and availability, then order with offer_code.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/locations/tree

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "countries": [
            {
                "country_code": "US",
                "country_name": "United States",
                "locations": [
                    {
                        "location_id": "loc_0123456789abcdef0123456789ab",
                        "country_code": "US",
                        "country_name": "United States",
                        "region": "Los Angeles"
                    }
                ]
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

List product tags

Get the ordinary and recommended categories present in the catalog.

Required scopeoffers:read

Request parameters

No additional business parameters. Signed request headers are still required.

• Directories support filtering, not a guarantee of stock for a quantity or duration. Check product quotes and availability, then order with offer_code.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/tags

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "tags": [
            {
                "code": "recommended",
                "name": {
                    "zh_CN": "推荐",
                    "en": "Recommended"
                }
            }
        ]
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Browse available products

List available products with prices, stock and selectable IP ranges.

Required scopeoffers:read

Request parameters

• Quotes use your account pricing, requested quantity and duration; they do not reserve stock. Prices and stock can change before purchase. Do not add stock counts from different products together. A stock value of null means unknown, not zero or unlimited.
• Calculate money with integer minor units or exact decimal arithmetic, not binary floating point. Decimal amount fields are strings with two places.
• Pass next_page_token back unchanged and keep the same filters and delivery mode. Tokens expire after 3 days. Continue while has_more is true, even after an empty page. Pages are not a frozen snapshot.
• The sandbox includes Standard, Recommended and CIDR test products, with per-range stock values of 3, 0 and null. null means unknown, not zero or total stock. Quantity limits apply per request; global stock depletion is not simulated. Returned connections are for testing and do not represent real exits in the selected range.
• Call this endpoint directly or use /offers?selection=highest_stock. Filter by quantity and duration, and use the price and selectable IP ranges from each product record. If you receive invalid_page_token, restart from the first page. Queries do not reserve stock.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/offers/available?page_size=200

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "currency": "CNY",
        "payment_mode": "wallet",
        "offers": [
            {
                "offer_code": "off_0123456789abcdef0123456789",
                "name": "United States - Los Angeles",
                "country_code": "US",
                "country_name": "United States",
                "region": "Los Angeles",
                "line_name": "United States - Los Angeles",
                "ip_type": "2",
                "protocol": "0",
                "unit_price_cents": 2000,
                "unit_price": "20.00",
                "base_duration_days": 30,
                "duration_days": [
                    30,
                    60,
                    90
                ],
                "max_quantity": 12,
                "cidrs": [
                    "198.51.100.0/24"
                ]
            }
        ],
        "page_size": 200,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get announcements

Read the currently published website announcement.

Required scopeaccount:read

Request parameters

• Returns the current website announcement: zero or one entry. has_more is false and next_page_token is null.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/announcements

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "environment": "production",
        "announcements": [
            {
                "announcement_id": "ann_0123456789abcdef0123456789ab",
                "title": {
                    "zh_CN": "公告",
                    "en": "Announcement"
                },
                "content": "PuppyIP service announcement.",
                "published_at": "2026-11-09T00:00:00+00:00"
            }
        ],
        "page_size": 20,
        "has_more": false,
        "next_page_token": null
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Update proxy credentials

Submit a credential update and check the result for each proxy.

Required scopeproxies:credentials

Request parameters

• Requires the separate proxies:credentials permission; existing keys do not gain it automatically. Available in production only when enabled, and in the sandbox with isolated simulated resources.
• Acceptance returns 202 processing. Replaying the same key and body returns the same operation’s current state; changing the body returns 409 idempotency_key_conflict. A new request overlapping an unresolved operation returns 409 operation_in_progress. Check each proxy’s result. Unresolved updates wait for confirmation without repeating the write. Successful snapshots do not rule out later changes.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.
• After a timeout, retry with the original Idempotency-Key and identical body bytes, using a fresh timestamp and nonce. Never change the key merely because the result is still pending.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

POST /api/v1/proxies/credentials
Content-Type: application/json
Idempotency-Key: example-credentials-001

{
    "proxy_ids": [
        "px_0123456789abcdef0123456789"
    ],
    "random": true
}

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 202

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "operation_id": "cop_documentation_example",
        "status": "processing",
        "successful_proxy_ids": [],
        "failed_proxy_ids": [],
        "unresolved_proxy_ids": [
            "px_0123456789abcdef0123456789"
        ],
        "proxies": []
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get a credential operation

Check confirmed and unresolved results for an operation.

Required scopeproxies:credentials

Request parameters

• Acceptance returns 202 processing. Replaying the same key and body returns the same operation’s current state; changing the body returns 409 idempotency_key_conflict. A new request overlapping an unresolved operation returns 409 operation_in_progress. Check each proxy’s result. Unresolved updates wait for confirmation without repeating the write. Successful snapshots do not rule out later changes.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/proxies/credential-operations/cop_documentation_example

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "operation_id": "cop_documentation_example",
        "status": "processing",
        "successful_proxy_ids": [],
        "failed_proxy_ids": [],
        "unresolved_proxy_ids": [
            "px_0123456789abcdef0123456789"
        ],
        "proxies": []
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get an asynchronous renewal

Check a submitted renewal without starting it again.

Required scopeproxies:write

Request parameters

• Omitting sync, or setting true, preserves the existing synchronous result. With sync=false, supply distinct proxy_ids. A new operation returns HTTP 202 with data={"operation_id":"rop_...","status":"processing"}; this is not a successful renewal. Poll GET /api/v1/proxies/renewal-operations/{operation_id}. Retrying the original key/body can replay the original acceptance, so query the operation for progress. Production requires asynchronous renewal to be enabled; sandbox uses isolated simulations.
• While processing, data contains only operation_id and status. A verified result adds the existing renewal amounts, per-item results, wallet and connection snapshot. If the result cannot be verified, manual_review can omit amount and wallet fields; omitted values do not mean zero or a refund. A pre-payment failure can include error and null line-item hosts; a changed quote fails without charging. Only confirmed failures are refundable. Do not create a new operation for unresolved items. Completed results are snapshots, so query each proxy for current connection details. external_order_no and remark are stored only for the asynchronous request and are not added to this response.
• Keep connection passwords and complete connection strings in trusted server-side storage, out of public pages and logs. Times use ISO 8601 with a UTC offset; null means unavailable, not zero.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/proxies/renewal-operations/rop_documentation_example

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "operation_id": "rop_documentation_example",
        "status": "processing"
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Get webhook settings

Read the callback subscription configured for this API key.

Required scopewebhooks:write

Request parameters

No additional business parameters. Signed request headers are still required.

• Each API key manages its own subscription and needs the separate webhooks:write permission; older keys do not gain it automatically. When disabled in production, POST configuration returns 403 feature_disabled; existing settings can still be read or disabled. Sandbox configuration and signature documentation are available for testing, but actual outbound delivery also requires sending to be enabled. A successful configuration response is not proof that sending is active.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

GET /api/v1/webhook

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "configured": true,
        "url": "https://example.com/puppyip-webhook",
        "events": [
            "order.updated",
            "renewal.updated",
            "proxy.updated"
        ],
        "version": 1
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Configure a webhook

Choose an HTTPS callback URL and the events you want to receive.

Required scopewebhooks:write

Request parameters

• Each API key manages its own subscription and needs the separate webhooks:write permission; older keys do not gain it automatically. When disabled in production, POST configuration returns 403 feature_disabled; existing settings can still be read or disabled. Sandbox configuration and signature documentation are available for testing, but actual outbound delivery also requires sending to be enabled. A successful configuration response is not proof that sending is active.
• Verify with the API Secret of the key that configured this webhook. X-PuppyIP-Timestamp is Unix time in seconds. Compute lowercase hexadecimal HMAC-SHA256 over PuppyIP-Webhook-v1\n<timestamp>\n<raw JSON body>, with each \n representing one LF byte. Compare with X-PuppyIP-Signature using a constant-time comparison; validate the timestamp against your accepted window and confirm X-PuppyIP-Event-ID equals body.event_id. Verify the raw bytes before parsing or re-encoding JSON.
• Only HTTP 200 acknowledges delivery. Return 200 for an already handled event_id as well. Delivery can repeat up to 10 attempts, with the same event_id and body but a fresh signing timestamp. Deduplicate event_id and do not assume arrival order or exactly-once delivery. A notification is a prompt to read current API state, not independent proof of payment or permission to charge again. Revoking the key, disabling the subscription or changing its configuration can cancel pending deliveries.
• The event object contains event_id, event, environment, occurred_at, observed_at, reason and data; it does not use the API success envelope. event is order.updated, renewal.updated or proxy.updated. Multiple changes to the same object may be combined into one notification. occurred_at is when that notification was first triggered; observed_at is when its reported state was observed. Retries keep the same body. Notifications may omit intermediate states.
• order.updated data: order_no, status, payment_status, currency and total_cents. proxy.updated data: proxy_id, status and expires_at. renewal.updated data: status, currency, total_cents, charged_cents, refunded_cents and the successful_proxy_ids, failed_proxy_ids and unresolved_proxy_ids lists. Unverified renewal amounts can be null, not zero. Notifications contain no connection passwords or connection strings; fetch current details with an authorized API request.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

POST /api/v1/webhook
Content-Type: application/json
Idempotency-Key: example-configure-webhook-001

{
    "url": "https://example.com/puppyip-webhook",
    "events": [
        "order.updated",
        "renewal.updated",
        "proxy.updated"
    ]
}

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "configured": true,
        "url": "https://example.com/puppyip-webhook",
        "events": [
            "order.updated",
            "renewal.updated",
            "proxy.updated"
        ],
        "version": 1
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Disable a webhook

Disable the callback subscription for this API key.

Required scopewebhooks:write

Request parameters

• DELETE requires a normal signed request, webhooks:write and Idempotency-Key. Within the 24-hour completed-response replay window, retry with the same API key, idempotency key and original body to replay that disable operation without disabling a subscription configured afterward. Use a new idempotency key for a new disable action. Normal API polling remains available.

Request example

The example shows the path and business parameters. Include signed headers in the actual request. View signing examples

DELETE /api/v1/webhook
Idempotency-Key: example-disable-webhook-001

Response fields

The table lists the complete response. Endpoint-specific business data is nested under data. View response envelope

Response example HTTP 200

{
    "success": true,
    "code": "ok",
    "message": "OK",
    "data": {
        "configured": false,
        "url": null,
        "events": [],
        "version": 2
    },
    "timestamp": "2026-11-09T00:00:00+00:00",
    "trace_id": "trc_documentation_example"
}

Stable pagination

GET /api/v1/offers?page_size=200

{
  "offers": [],
  "page_size": 200,
  "has_more": true,
  "next_page_token": "opaque-token-from-response"
}

For the next page, pass the returned next_page_token unchanged as page_token and keep the same page_size and filters, for example GET /api/v1/offers?page_size=200&page_token=.... Route, order and IP lists use the same response fields. Routes allow up to 200 entries per page; order and IP page limits are enforced by their respective endpoints. Tokens are bound to the current account, environment, resource type and route filters. Tampered, expired, cross-account tokens or tokens used with changed filters are rejected.

Stop paging only when has_more=false. If has_more=true, continue with next_page_token even when offers is empty or contains fewer than page_size entries. Pages read current data, not a frozen catalog snapshot. Periodically restart from the first page, deduplicating and updating by offer_code.

Order states and sandbox scenarios

After order creation returns 201, use the returned PuppyIP order_no to query GET /api/v1/orders/{order_no}.paid or procuring means processing. When poll_after_seconds is an integer, wait that many seconds before the next query. Stop polling when it is null or the order reaches a terminal state. For HTTP 429, follow Retry-After first. The proxies in order details may be delivered to the customer only when delivery.available=true .

{
  "order_no": "SANDBOX_ORDER_EXAMPLE",
  "status": "procuring",
  "payment_status": "paid",
  "delivery": {
    "expected_count": 3,
    "delivered_count": 1,
    "complete": false,
    "available": false
  },
  "poll_after_seconds": 1,
  "refund": null,
  "proxies": []
}

Partial-delivery read mode (optional)

GET /api/v1/orders/{order_no}
X-PuppyIP-Delivery-Mode: partial

Both production and sandbox support this optional header only for GET /api/v1/orders, GET /api/v1/orders/{order_no}, GET /api/v1/proxies and GET /api/v1/proxies/{proxy_id}. If omitted or not set to partial, each environment retains its existing response fields, statuses and read behavior. Production retains the complete-order delivery gate. Sandbox order responses retain that gate, while sandbox proxy lists and details retain their account- and sandbox-identifier-scoped access to test resources. Existing clients need no changes. This does not affect POST requests, raw JSON signatures, Idempotency-Key or historical response replays.

When enabled, paid, delivered IPs still owned by the current account can be read immediately. Unpaid, fully refunded, missing or transferred resources remain unavailable. delivery.available=true means resources are currently available; only delivery.complete=true means the entire order is delivered. Orders may show partially_delivered. procurement_blocked still means the outcome is unsettled, not full success; continue following poll_after_seconds.

Only with this mode enabled, delivery in order details and lists adds delivery.remaining_count. While unsettled, it equals the original expected quantity minus currently delivered IPs and confirmed per-item refund quantities, with a minimum of 0. It is 0 after complete fulfillment, a full refund or cancellation. Missing resources from historically completed orders are not counted as pending delivery. expected_count retains the original purchased quantity; see refund separately for partial refunds. Order lists still do not return proxy credentials.

Pagination tokens are bound to the delivery read mode. Keep the same header when paging. Switching modes requires starting again from the first page; otherwise the response is 422 invalid_page_token. Deleting a revoked API key does not erase unexpired completed responses or unsettled idempotency records. Retrying with a new key must still use the original Idempotency-Key and raw body. Changing credentials must not re-execute the same purchase.

Common errors

invalid_signature

Missing signature, incorrect App ID, inconsistent canonical string construction or the wrong API Secret.

stale_timestamp

The timestamp lacks a timezone, is not ISO 8601, or differs from the server clock by more than 5 minutes.

replayed_nonce

The same nonce was reused with one API key. Generate a new random nonce for every request.

idempotency_key_required

A request requiring Idempotency-Key is missing the header, or its length or characters are invalid.

idempotency_key_conflict

The same Idempotency-Key has already been used with a different request body.

idempotency_processing / idempotency_replay_failed

The operation is still processing, or the original response cannot yet be safely replayed. Keep the same key and raw body, then retry later as directed by the response.

idempotency_unresolved

HTTP 409. The earlier request may already have charged funds or produced another outcome and requires review. Do not assume an error or timeout means nothing executed, and do not automatically retry with a new key.

insufficient_scope

The API key lacks the required permission, or the request's source IP is outside the allowed range.

api_key_revoked

The API key has been revoked. Use a valid key with the required permissions.

validation_error

Request fields, quantity, duration or combinations do not meet endpoint constraints. Correct them according to data.errors before resubmitting.

offer_not_found / order_not_found / proxy_not_found

The public identifier does not exist, is unavailable or does not belong to the current account and environment. Retrieve the relevant list again.

insufficient_wallet_balance

Insufficient wallet balance. The order or renewal was not successfully charged.

invalid_page_token

The pagination token has expired, been modified or been used with the wrong account, environment or resource. Start again from the first page.

rate_limited

Requests are too frequent. Read Retry-After before retrying. Do not poll continuously without a delay.

unsupported_operation

The operation is not available in Customer API v1, such as IP replacement or trial IPs.

proxy_endpoint_unavailable / operation_failed

The connection endpoint is unavailable or the operation is incomplete. Keep trace_id and follow the retry guidance for the response status, or contact support.