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

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.