Error handling

The SDK separates local configuration/validation failures, transport failures, and HTTP API failures.

Exception	Meaning
OkatanaConfigurationException	invalid URL, missing API key, invalid global policy
OkatanaRequestValidationException	request violates a local OpenAPI constraint
OkatanaTransportException	timeout or HTTP transport failure
OkatanaAuthenticationException	401
OkatanaAuthorizationException	403
OkatanaNotFoundException	404
OkatanaValidationException	422
OkatanaRateLimitException	429
OkatanaApiException	other non-success HTTP status
OkatanaUnexpectedResponseException	success payload cannot be interpreted safely

Laravel validation errors are retained:

try
{
    await client.Tickets.UpdateAsync(ticketId, request);
}
catch (OkatanaValidationException ex)
{
    foreach (var (field, messages) in ex.Errors)
        foreach (var message in messages)
            Console.Error.WriteLine($"{field}: {message}");
}

Business-rule 422 responses may contain only message; therefore do not assume Errors is non-empty.

Do not retry 401, 403, or request-correctness 422 failures without changing the credential or request. A 404 can mean a resource is absent, soft-deleted, or not valid inside a constrained relationship.