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

# Error Handling

> Handle API errors with typed error classes and automatic retries.

The SDK throws typed error classes for different failure scenarios. All errors extend `RoyaltyportError`, which extends the built-in `Error` class.

## Error Classes

| Class                            | HTTP Status | Description                         |
| -------------------------------- | ----------- | ----------------------------------- |
| `RoyaltyportError`               | Any         | Base error class for all API errors |
| `RoyaltyportAuthenticationError` | `401`       | Missing, invalid, or expired token  |
| `RoyaltyportRateLimitError`      | `429`       | Rate limit exceeded                 |
| `RoyaltyportValidationError`     | `400`       | Invalid or missing parameters       |

## Properties

All error classes include:

| Property    | Type                    | Description                              |
| ----------- | ----------------------- | ---------------------------------------- |
| `message`   | `string`                | Human-readable error description         |
| `status`    | `number`                | HTTP status code                         |
| `rateLimit` | `object` or `undefined` | Rate limit information from the response |

`RoyaltyportRateLimitError` also includes:

| Property     | Type                    | Description                               |
| ------------ | ----------------------- | ----------------------------------------- |
| `retryAfter` | `number` or `undefined` | Unix timestamp when the rate limit resets |

***

## Usage

```js theme={null}
import {
  Royaltyport,
  RoyaltyportAuthenticationError,
  RoyaltyportRateLimitError,
  RoyaltyportValidationError,
} from '@royaltyport/sdk';

const royaltyport = new Royaltyport({ apiKey: 'rp_your_token_here' });

try {
  const { data } = await royaltyport.projects.list();
} catch (error) {
  if (error instanceof RoyaltyportAuthenticationError) {
    console.error('Invalid or expired token');
  } else if (error instanceof RoyaltyportRateLimitError) {
    console.error(`Rate limited. Retry after: ${error.retryAfter}`);
  } else if (error instanceof RoyaltyportValidationError) {
    console.error('Invalid request:', error.message);
  } else {
    throw error;
  }
}
```

***

## Automatic Retries

The SDK automatically retries requests on `429` and `5xx` errors:

* Up to **3 retries** per request
* **Exponential backoff** starting at 500ms (max 60s)
* `Retry-After` headers from rate limit responses are respected

No configuration is required. If all retries are exhausted, the corresponding error is thrown.