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

# Error Handling

> How the Nexudus SDK handles errors, rate limiting, and edge cases.

# Error Handling

The SDK uses a consistent approach to error handling across all operations.

## Behaviour by operation

| Operation     | On failure                                                     |
| ------------- | -------------------------------------------------------------- |
| `CreateAsync` | Throws `InvalidOperationException` with the API error message. |
| `UpdateAsync` | Throws `InvalidOperationException` with the API error message. |
| `DeleteAsync` | Throws `InvalidOperationException` with the API error message. |
| `GetAsync`    | Returns `null` when the entity is not found.                   |
| `SearchAsync` | Returns an empty `SearchResult<T>` on failure.                 |

## Catching errors

```csharp theme={null}
try
{
    long id = await endpoint.CreateAsync(entity);
}
catch (InvalidOperationException ex)
{
    // ex.Message contains the API error details
    Console.WriteLine($"API error: {ex.Message}");
}
```

## Rate limiting

The SDK automatically retries requests that receive an HTTP `429 Too Many Requests` response. Retries use **exponential backoff**, so you don't need to implement retry logic yourself.

## Response types

For advanced scenarios, the SDK exposes the raw `ApiResponse<T>` envelope:

| Property        | Type     | Description                                  |
| --------------- | -------- | -------------------------------------------- |
| `Value`         | `T`      | The deserialized response body.              |
| `WasSuccessful` | `bool`   | Whether the API call succeeded.              |
| `Message`       | `string` | Error or informational message from the API. |
| `StatusCode`    | `int`    | The HTTP status code.                        |