Response patterns

Pxxl SDK methods return the useful resource directly when possible. You do not need to inspect HTTP status codes for successful calls.

Single resources

Create and get methods return a resource or a small named wrapper.

{
  "bucket": {
    "id": "bucket_123",
    "name": "uploads",
    "visibility": "private",
    "status": "active"
  }
}

When a Node.js method unwraps the resource, you receive the inner object directly. For example, customers.create() returns the customer and cdn.upload() returns the asset.

SDK	How successful JSON is returned
Node.js	Typed resources where available, with small API wrappers kept when they contain useful metadata
Go	Typed structs for core workflows and `map[string]any` for extensible platform responses
Python	Dictionaries that preserve the Gateway JSON shape
Rust	Typed core resources and `serde_json::Value` for extensible platform responses

Lists

List methods return an array with count or pagination details.

{
  "buckets": [],
  "total": 0
}

{
  "assets": [],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 0,
    "totalPages": 0
  }
}

Actions

Start, stop, trigger, resync, and delete calls return an action result. Delete helpers that return no useful data resolve without a value.

{
  "success": true,
  "message": "Action accepted"
}

Files

Download methods return binary data instead of JSON.

SDK	Return value
Node.js	`Blob`
Go	response bytes or a readable body
Python	`bytes`
Rust	`Vec<u8>` or response bytes

Errors

Non-successful API responses throw an SDK error. The original API response remains available for validation errors and plan limits.

{
  "code": "DOMAIN_LIMIT_EXCEEDED",
  "message": "Your current plan domain limit has been reached.",
  "limit": 5,
  "used": 5
}

Node.js
Go
Python
Rust

try {
  await pxxl.storage.createBucket({ name: "uploads" });
} catch (error) {
  if (error instanceof PxxlAPIError) {
    console.log(error.status, error.code);
    console.log(error.limit, error.current, error.requiredPlan);
  }
}

result, err := client.CreateStorageBucket(ctx, input)
if err != nil {
  var apiErr *pxxl.APIError
  if errors.As(err, &apiErr) && apiErr.IsPlanGate() {
    log.Println(apiErr.Code, apiErr.Limit, apiErr.Current, apiErr.RequiredPlan)
  }
}

from pxxl import is_plan_gate_error

try:
    result = client.create_storage_bucket(input)
except PxxlAPIError as error:
    if is_plan_gate_error(error):
        print(error.code, error.limit, error.current, error.required_plan)

if let Err(error) = client.create_storage_bucket(input).await {
    if error.is_plan_gate() {
        eprintln!("Upgrade required for another storage bucket");
    }
}

Node.js also exports isPlanGateError(error). Structured plan-gate handling works across storage, domains, deployments, databases, and cron jobs.

Response examples show the fields used most often. The API can add fields without breaking existing integrations.

​Single resources

​Lists

​Actions

​Files

​Errors

Single resources

Lists

Actions

Files

Errors