> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pxxl.app/llms.txt
> Use this file to discover all available pages before exploring further.

# Response patterns

> Understand returned data, lists, files, empty results, and errors across every Pxxl SDK.

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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "buckets": [],
  "total": 0
}
```

```json theme={null}
{
  "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.

```json theme={null}
{
  "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.

```json theme={null}
{
  "code": "DOMAIN_LIMIT_EXCEEDED",
  "message": "Your current plan domain limit has been reached.",
  "limit": 5,
  "used": 5
}
```

<Tabs>
  <Tab title="Node.js">
    ```ts theme={null}
    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);
      }
    }
    ```
  </Tab>

  <Tab title="Go">
    ```go theme={null}
    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)
      }
    }
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Rust">
    ```rust theme={null}
    if let Err(error) = client.create_storage_bucket(input).await {
        if error.is_plan_gate() {
            eprintln!("Upgrade required for another storage bucket");
        }
    }
    ```
  </Tab>
</Tabs>

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

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


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.