Platform integration errors

Platform API responses and webhook deliveries are application-layer contracts. Diagnose them separately from gateway traffic and preserve the complete sanitized JSON or delivery body before retrying. For HTTP proxy and SOCKS5 failures, use proxy errors and troubleshooting.

Fast diagnostic path

1. Identify whether the failure came from an API request, a webhook delivery, or your local processing.
2. Record the deployment, UTC time, method, path, status, and affected resource IDs.
3. Preserve the complete sanitized JSON response or the exact verified webhook body.
4. Confirm the authorization type, account role, ownership scope, and target deployment.
5. Check whether a write completed before retrying a timeout or 5xx response.
6. Reconcile webhook-driven state against the API and analytics for a closed reporting window.

Identify the failing layer

API contract

Request validation, authorization, ownership, business rules, or rate limits rejected the operation with a structured response.

Platform service

A platform component or dependency failed before the operation could return a successful response.

Webhook receiver

Signature verification, payload processing, acknowledgment, or local customer mapping failed after an event was delivered.

Platform API status checklist

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
409	A reused key conflicts with the request, or an operation is still processing	Switch to a new key to force a duplicate purchase
412	The resource changed since your ETag was read	Remove If-Match and overwrite the newer state
429	API request rate exceeded for the deployment	Launch parallel immediate retries
5xx	Platform service or dependency failure	Repeat state-changing writes without checking state

API error payloads

The API can return dynamic field arrays in addition to detail and non_field_errors. Internal translation metadata is removed from public responses. Use Accept-Language and inspect Content-Language; do not parse localized prose as a stable machine code. Preserve the sanitized body.

Common provisioning failures

Symptom	Check next
Data-add returns 400	Send both package_id and positive integer-byte data; verify the parent owns a root order for that package
Child has quota but proxy access fails	Check usable parent data, expiration, user/order state and gateway credentials
Invoice creation returns 403 with status=paid	Only is_superuser permits that value; reseller or staff status alone does not
Invoice is paid but no usable order appears	Poll the existing invoice and customer orders with a deadline; fulfillment recovery can be asynchronous
Checkout initialization returns 502	Preserve invoice_id if returned and inspect the existing purchase; do not blindly create a new invoice
/sessions returns 403	Session listing/deletion is currently unavailable; sticky generation itself remains supported
Order remaining data falls without matching traffic	A purchased bucket may have expired; compare its deadline, not only usage

For exact retry behavior, use reliable requests. For data semantics, start with purchases and traffic.

API errors are not gateway responses

API errors use JSON contracts and API authorization. Gateway errors use proxy protocol responses and proxy credentials. Never place a proxy username or password in the API Authorization header.

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

Return a direct 2xx only after the delivery has been verified and durably accepted. Retries can repeat the same batch, so local updates must be safe to process more than once. See webhook integration and the webhook event reference for the exact signature and payload contracts.

Platform escalation record

Include:

• deployment and affected API hostname or webhook endpoint;
• UTC start and end time;
• API method and path, or webhook delivery context;
• status code and complete sanitized response body;
• user, order, package, invoice, API key, or webhook IDs;
• whether the operation was read-only or could have completed before failure;
• whether API, analytics, webhook, and local state disagree.

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