Common errors and troubleshooting

Start at the lowest failing layer. Changing credentials, targeting, and application code at the same time makes a simple network problem harder to isolate.

Fast diagnostic path

1. Resolve the assigned gateway or API hostname from the same host as the application.
2. Test TCP connectivity to the assigned protocol port.
3. Run a minimal cURL request with verbose output and no optional targeting.
4. Record the exact HTTP status, SOCKS5 reply, or connection-close stage.
5. Add one targeting or session token at a time.
6. Compare the failing request with a known-good package or user.
7. Record the UTC time, deployment, resource IDs, and sanitized response before escalating.

HTTP verbose test

curl --verbose \
  --proxy http://USERNAME:[email protected]:8000 \
  https://api.ipify.org?format=json

SOCKS5h verbose test

curl --verbose \
  --proxy socks5h://USERNAME:[email protected]:1080 \
  https://api.ipify.org?format=json

Identify who produced the response

Gateway-generated

The proxy rejected authentication, targeting, protocol input, allocation, policy, concurrency, or an internal connection step.

Upstream or destination

An upstream proxy or destination returned the status. Its headers and body can pass through, or a deployment-specific provider rule can replace them.

Client-side transport

DNS, TCP, TLS, or SOCKS negotiation failed before an HTTP response existed. The client may report an EOF, reset, or timeout instead of a status code.

Gateway HTTP errors do not use a JSON body

Native gateway errors contain a status line, Connection: close, and an empty body. A 407 response also includes Proxy-Authenticate: Basic realm="Invalid credentials". Do not make retry decisions by waiting for a detail field that is not sent by the gateway.

HTTP gateway status catalog

The first table covers statuses emitted by active proxy request paths. Retry only when the request is safe to repeat.

Status	When the gateway emits it	Client action	Retry
400 Bad Request	HTTP traffic is disabled on this gateway. Malformed HTTP input is handled as 409, not 400.	Use a gateway and port that enable HTTP, or switch to an enabled protocol.	No, until configuration changes
402 Payment Required	The user has no allocatable data, or the allocation is exhausted while the gateway reads or writes a response.	Replenish data, verify the assigned order, and start a new connection.	After allocation changes
406 Not Acceptable	Session length or TTL, package syntax, filter duration, targeting, location, or targeted provider is invalid or unavailable.	Remove optional tokens, validate them individually, and rebuild the proxy username.	No, with unchanged targeting
407 Proxy Authentication Required	Proxy-Authorization is missing or malformed; credentials, user, package, or targeting record cannot be authenticated.	Reissue the package username and proxy password. Confirm that the order and user are active.	No, with the same credentials
409 Conflict	The request cannot be read, has no host, uses a blocked direct IP, or the gateway cannot write the response to the client connection.	Send a valid proxy-form request with a hostname and inspect the client/network connection.	Only after correcting the request or connection
410 Gone	Provider credential generation, deadlines, upstream reads/writes, or the initial client response failed after processing began.	Open a new connection and preserve the failed request time for diagnostics.	Yes, with bounded backoff for idempotent work
417 Expectation Failed	An unexpected username parsing, authentication, or routing error occurred.	Retry once, then escalate with deployment, UTC time, and sanitized credentials shape.	Limited
429 Too Many Requests	The package connection limit is reached or the active-connection record cannot be created.	Reduce concurrency, close abandoned connections, and apply backoff with jitter.	Yes, after capacity is available
451 Unavailable For Legal Reasons	The requested hostname or top-level domain is blocked by gateway policy.	Change the destination or request a policy review.	No, with the same destination
500 Internal Server Error	The proxy reaches an unspecified internal error or an unmapped error status.	Retry safe work once and escalate repeated failures with the UTC time and gateway.	Limited
502 Bad Gateway	Target DNS resolution fails while an HTTP request is being transported through a SOCKS5 upstream.	Verify the target hostname and resolver reachability.	Yes, if the failure is transient
504 Gateway Timeout	No configured upstream candidate can be dialed. Provider-specific error normalization also defaults to 504.	Retry with backoff, broaden targeting, and check provider availability.	Yes, with backoff

Supported templates and upstream statuses

The proxy contains native response templates for the following statuses, but no active proxy-request path emits them directly. They can still be received from an upstream or produced by deployment-specific provider error overrides.

Status	Likely owner	Client action
403 Forbidden	Upstream policy, destination policy, or a configured override	Verify account and destination policy; do not retry unchanged.
412 Precondition Failed	Upstream or a configured override	Inspect upstream requirements and deployment-specific routing rules.
501 Not Implemented	Upstream or a configured override	Use a supported feature or protocol.
503 Service Unavailable	Upstream, configured override, or the gateway readiness endpoint	Back off and verify deployment/provider health.

An upstream HTTP response is not restricted to this list. Preserve its sanitized headers and body because provider and destination responses can use any valid HTTP status. A provider rule may also reset the original response and replace it with another configured status.

Debug headers can contain sensitive upstream data

Debug-enabled responses may include deployment-named headers for the upstream address, provider credentials, targeting, and provider details. Remove them, proxy passwords, and full proxy URLs before sharing a trace.

SOCKS5 failure catalog

SOCKS5 does not receive the HTTP statuses above. Diagnose the stage and byte value reported by the client library.

Stage or reply	Meaning in the current gateway	Client action
Negotiation 0xFF	The client did not offer username/password authentication.	Enable SOCKS5 username/password authentication in the client.
User/password 0x01	Authentication failed. Invalid credentials, session, targeting, filter, allocation, or policy failures are intentionally collapsed into one reply.	Rebuild credentials with minimal targeting and verify allocation.
REP 0x01	General server failure forwarded by a SOCKS5 upstream.	Retry with backoff and inspect provider health.
REP 0x02	Connection not allowed, forwarded by a SOCKS5 upstream.	Review provider or destination policy.
REP 0x03	Network unreachable, forwarded by a SOCKS5 upstream.	Check provider routing and retry with backoff.
REP 0x04	Host unreachable, forwarded by a SOCKS5 upstream.	Verify the destination and DNS behavior.
REP 0x05	The gateway rejected a malformed request, invalid destination, or routing failure; an upstream can also return connection refused.	Validate the destination and retry only if refusal may be transient.
REP 0x06	TTL expired, forwarded by a SOCKS5 upstream.	Retry with another route or provider.
REP 0x07	The requested command is unsupported. The gateway accepts CONNECT and UDP ASSOCIATE.	Use a supported command.
REP 0x08	The address type is unsupported or conflicts with the enabled SOCKS5/SOCKS5h mode.	Use a hostname for SOCKS5h or an IP for SOCKS5, as configured.
EOF or reset before final reply	Provider dialing or negotiation failed, an auth packet was malformed, or the connection closed before a SOCKS reply could be written.	Record the failing stage and test the same credentials through the HTTP gateway.
Disconnect after success	Relay, accounting, or connection-limit handling terminated an already accepted connection.	Check concurrency and remaining data, then reconnect with backoff.

When the selected provider supports SOCKS5, its final REP byte is forwarded to the client. Treat non-standard values as provider-specific and include the raw byte in an escalation record.

Platform API status checklist

Platform API responses are JSON contracts and are separate from gateway traffic.

Status	Meaning to investigate	Do not do
400	Body shape, required field, resource state, or business rule	Retry the same invalid body continuously
401	Missing, expired, or invalid API authorization	Send proxy credentials as API credentials
403	Role, ownership, or account scope	Hide the denial and continue later steps
404	Wrong ID, wrong deployment, or inaccessible resource scope	Assume the global resource does not exist
429	API request rate exceeded for the deployment	Launch parallel immediate retries
5xx	Platform service or dependency failure	Repeat non-idempotent writes without checking state

The API can return dynamic field arrays in addition to detail, non_field_errors, and translation. Preserve the full sanitized body in internal diagnostics.

Webhook failures

Failure	Check
Signature mismatch	Raw bytes were verified before JSON parsing; Base64 was not converted to hex
Repeated deliveries	Endpoint returned an error, timed out, or the acknowledgment was lost
Missing individual update	Several changes may have been coalesced into one latest-balance event
Incorrect customer mapping	Use user.id, user.reseller_id, order.id, and package.id—not user.username alone
Local total differs from report	Run analytics reconciliation for a closed UTC window

Escalation record

Include:

• deployment and affected API or gateway hostname;
• UTC start and end time;
• protocol and sanitized request shape;
• HTTP status, SOCKS5 stage and reply byte, or transport error;
• sanitized response headers and body when present;
• user, order, package, or webhook IDs;
• whether the failure reproduces with broad targeting;
• whether analytics and webhook state disagree.

Use Book a Demo / Contact for an implementation review, or browse the generated API Reference for exact operation contracts.