Error handling

The SOAX API uses conventional HTTP status codes. Anything in the 2xx range is success, 4xx means something is wrong with the request, and 5xx means something went wrong on the SOAX side.

Error response shapes

Errors return a JSON object with the message under one of two keys, depending on which validation layer rejected the request. Endpoint-level checks (auth, scopes, not-found, pagination and count limits) use detail:

{ "detail": "Package not found" }

Deeper business-rule validation — connection-string rule combinations, analytics date ranges and filters, API key creation rules — and shared API rate-limit errors use error:

{ "error": "Cannot specify both 'rotate-time' and 'rotate-requests' simultaneously." }

Stateful-session create and rotate limits can also return 429 with a detail message. See the Stateful Sessions guide. The split is an implementation detail you shouldn’t depend on — in your error handling, read detail ?? error and treat them the same. The tables below show which key each message actually uses. 422 validation errors (a parameter or body field failed type/format validation) are the third shape: a detail array, one entry per problem, with the location of the offending field:

{
  "detail": [
    {
      "loc": ["query", "limit"],
      "msg": "Input should be less than or equal to 100",
      "type": "less_than_equal"
    }
  ]
}

Status codes

Code	Meaning	How to handle
`200`	Success	—
`201`	Created (new API key)	Store the returned `secret` immediately — it is never shown again.
`204`	Success, no body (key revoked)	—
`400`	Invalid parameter value	Don’t retry as-is. The `detail` message names the parameter and, where applicable, lists valid values. Fix the request.
`401`	Missing, invalid, or revoked API key	Don’t retry. Check the `Authorization: Bearer <secret>` header and the key’s status. If the key was revoked, create a new one.
`403`	Key lacks the required scope, or your plan lacks a feature	Don’t retry. Either use a key with the right scope (the `detail` names it), or — for ASN/ZIP location endpoints — upgrade to a plan with that targeting feature.
`404`	Resource not found	Don’t retry. The resource doesn’t exist, belongs to another organization, or is outside the key’s package restriction (restricted keys get 404, never 403, for packages they can’t see).
`422`	Request failed schema validation	Don’t retry as-is. Fix the field named in `loc`.
`429`	Rate limit exceeded	Wait the number of seconds in the `Retry-After` header, then retry. See Rate limits.
`5xx`	Server error	Retry with exponential backoff. If it persists, contact support with the `x-request-id` response header value.

Every response includes an x-request-id header. Log it — support can trace exactly what happened to a request from that ID.

Common error messages

Messages under the detail key:

Status	`detail`	What it means
401	`Invalid API key`	No key sent, the secret is wrong, or the key was revoked.
403	`Missing required scope: <scope>`	The key doesn’t carry the scope this endpoint requires. See scopes.
403	`Feature asn_targeting is not enabled` / `Feature zip_code_targeting is not enabled`	Your plan doesn’t include ASN or ZIP targeting (ASNs, ZIP codes).
404	`Package not found`	Wrong package ID, another organization’s package, or outside the key’s package restriction.
404	`API key not found`	The `key_id` being revoked doesn’t exist in your organization.
404	`No active subscription found`	The account has no active subscription.
400	`Invalid status value: … Valid values are: active, deleted, limited, paused, suspended`	Bad `status` filter on list packages. One value only — comma-separated lists are rejected.
400	`Count cannot exceed 1000.`	`count` on connection strings is above the maximum.
400	`Country code '…' is not available for this package.`	A package location endpoint was called with a country the package can’t target. List valid ones via package countries.
400	`Network '…' is not available for this package. Available networks: …`	Bad `network` filter on a package location endpoint; the message lists what the package supports.

Messages under the error key:

Status	`error`	What it means
400	`Country '…' is not available for this proxy package.`	Connection strings requested for a country the package can’t target.
400	`Invalid network '…'. Must be one of: residential, mobile, any.`	Bad `network` value on connection strings.
400	`Country must be specified if region, city, ISP, ASN, or ZIP is provided.`	Finer-grained targeting always needs `country`.
400	`Cannot specify both 'rotate-time' and 'rotate-requests' simultaneously.`	Pick one rotation mode.
400	`The 'retries' parameter is required when onerror='retry'.`	`on-error=retry` needs `retries`; `retries` is only valid with `on-error=retry`.
400	`Session ID must be an alphanumeric lowercase string up to 16 characters.`	`session` must match `^[a-z0-9]{1,16}$`.
400	`bind=node is incompatible with prefer=lookalike.` / `…with onerror=replace.`	A bound session can’t be replaced, so replacement-based options don’t apply.
400	`Date range cannot be more than 1 year`	An analytics query spans more than 365 days.
400	`hour interval requires a date range less than 24 hours`	See interval constraints in Rate limits; `day` and `month` have analogous messages.
400	`Invalid scopes: … Valid scopes are: …`	Creating a key with an unknown scope.
400	`Requested scopes exceed the calling key's own scopes`	Creating a key with more scopes than the caller has.
429	`Rate limit exceeded: …`	Too many requests. Wait `Retry-After` seconds.

Handling errors in code

A pattern that covers the cases worth automating — retry 429 and 5xx, surface everything else:

import time
import requests

def soax_request(method, url, *, api_key, max_attempts=5, **kwargs):
    headers = {"Authorization": f"Bearer {api_key}"}
    for attempt in range(max_attempts):
        resp = requests.request(method, url, headers=headers, **kwargs)
        if resp.status_code == 429:
            time.sleep(int(resp.headers.get("Retry-After", 1)))
            continue
        if resp.status_code >= 500:
            time.sleep(min(2 ** attempt, 30))  # exponential backoff, capped
            continue
        if resp.status_code >= 400:
            body = resp.json()
            message = body.get("detail") or body.get("error") or body
            raise RuntimeError(
                f"SOAX API error {resp.status_code}: {message} "
                f"(x-request-id: {resp.headers.get('x-request-id')})"
            )
        return resp.json() if resp.status_code != 204 else None
    raise RuntimeError(f"Gave up after {max_attempts} attempts: {url}")

async function soaxRequest(url, { apiKey, maxAttempts = 5, ...init } = {}) {
  for (let attempt = 0; attempt < maxAttempts; attempt++) {
    const resp = await fetch(url, {
      ...init,
      headers: { Authorization: `Bearer ${apiKey}`, ...init.headers },
    });
    if (resp.status === 429) {
      const retryAfter = Number(resp.headers.get("Retry-After") ?? 1);
      await new Promise((r) => setTimeout(r, retryAfter * 1000));
      continue;
    }
    if (resp.status >= 500) {
      await new Promise((r) => setTimeout(r, Math.min(2 ** attempt * 1000, 30000)));
      continue;
    }
    if (!resp.ok) {
      const body = await resp.json().catch(() => ({}));
      const message = body.detail ?? body.error ?? JSON.stringify(body);
      throw new Error(
        `SOAX API error ${resp.status}: ${message} ` +
        `(x-request-id: ${resp.headers.get("x-request-id")})`
      );
    }
    return resp.status === 204 ? null : resp.json();
  }
  throw new Error(`Gave up after ${maxAttempts} attempts: ${url}`);
}

These are errors from the API (api.platform.soax.com). Errors from the proxy gateway (proxy.soax.com:1337, e.g. 407 AUTH_FAILED) are a different system with different codes — see Proxy error codes.

Getting Started

Proxies

Dashboard

Trust & Safety

API Reference

Code Examples

Troubleshooting

Error handling

Error response shapes

Status codes

Common error messages

Handling errors in code