# Reference

## Error handling

The SDK returns several different types of errors based on the HTTP response, ranging from 401 to 422. They are exposed and can be imported:


```js
import { RebillyErrors } from 'rebilly-js-sdk';
```

### Error types

| Type | Status code | Description |
|  --- | --- | --- |
| `RebillyRequestError` | `-` | Generic error when no response is available. |
| `RebillyTimeoutError` | `-` | The request timed out. |
| `RebillyCanceledError` | `-` | The request was canceled before being completed. |
| `RebillyForbiddenError` | `401` | Indicates an invalid API key or expired session token. |
| `RebillyNotFoundError` | `404` | Requested resource was not found. |
| `RebillyMethodNotAllowedError` | `405` | Request method not allowed on this resource. |
| `RebillyConflictError` | `409` | Requested operation triggered a conflict. |
| `RebillyValidationError` | `422` | The request payload triggered a validation error (see error details). |


## Configuration options

All client API configuration parameters are optional. However, a secret API key can only be provided at instantiation.

> **API environments**
By default a client instance is always generated in the **Live** environment. The **Sandbox** mode is only recommended while developing your integration.


| Option | Type | Description |
|  --- | --- | --- |
| `apiKey` | `string` | Your secret API key. To be used only for server-side integration. See [Developer > API Keys](https://app.rebilly.com/api-keys). |
| `sandbox` | `boolean` | Flag used to enable sandbox mode for the instance. This allows you to run requests without processing real transactions on your account. Defaults to `false`. |
| `timeout` | `integer` | Define the timeout in milliseconds for API requests. Defaults to `6000`. |
| `organizationId` | `string` | Your organization identifier in scope of which need to perform request (if not specified, the default organization will be used). |
| `urls` | `object` | Define the root URLs for `live` and `sandbox` mode. Object must have a key for each mode that have strings for values. Defaults to `{live: 'https://api.rebilly.com', sandbox: 'https://api-sandbox.rebilly.com'}` |


## Collections, members, and files

All resource calls return either a File, Member, or Collection:

- `getAll` always returns a `Collection`, which contains a list of Members
- CSV or PDF downloads will return a `File`
- All other methods return a `Member`


> **Frozen objects**
Both collections and Members are **immutable** (frozen). Attempting to modify either one directly will result in a `TypeError`. You can retrieve a plain JSON object for mutation using the `getJSON` method.


### Collection

The collection type represents a list of Members (e.g. a list of customers, a list of transactions).

Each collection instance exposes the same properties.

| Name | Type | Description |
|  --- | --- | --- |
| items | Array<Member> | An array of member entities. See the [Member type](#member) for details. |
| total | number | An integer defining the total amount of members that exist regardless of the requested limit. |
| limit | number | An integer defining the count of values returned by the API request. Reflects the `limit` value passed to the function which returned the Collection. |
| offset | number | A zero-based index defining the starting position for the requested members. |
| response | Object | The original response stripped down to the status code, status text and headers. Exposes three more properties: `{status, statusText, headers}`. |
| getJSON | Function | Returns a plain mutable JSON object exposing the `items` of the current collection instance. Discards all other property. |
| config | Object | An object literal with the original request query string parameters. |


### Member

The member type represents an instance of a single resource entity in Rebilly (e.g. one customer, one transaction).

Each member instance exposes the same properties.

| Name | Type | Description |
|  --- | --- | --- |
| fields | Object | An object literal with key-value pairs for each field returned by the API in the response. |
| response | Object | The original response stripped down to the status code, status text and headers. Exposes three more properties: `{status, statusText, headers}`. |
| getJSON | Function | Returns a plain mutable JSON object exposing the `fields` of the current member instance. Discards the `response` property. |
| config | Object | An object literal with the original request query string parameters. |


### File

The file type allows you to access the `arraybuffer` data from API requests that return files. The files can be either exported CSV data or generated invoice PDFs.

You can generate a binary file to download from the file content directly in the browser, or save it locally using the file system in Node.js.

Each file instance exposes the same properties.

| Name | Type | Description |
|  --- | --- | --- |
| data | Object | An `arraybuffer` containing the file data returned by the request. See [ArrayBuffer](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ArrayBuffer). |
| response | Object | The original response stripped down to the status code, status text and headers. Exposes three more properties: `{status, statusText, headers}`. |
| config | Object | An object literal with the original request query string parameters. |