Errors and retries

How failed requests are reported, and which requests are retried.

Errors

A call that fails with an HTTP error status throws an ApiException.

try
{
    await client.LookupIPAsync(IPAddress.Parse("8.8.8.8"));
}
catch (ApiException e) when (e.StatusCode == 402)
{
    Console.WriteLine("out of lookup credits");
}
catch (ApiException e) when (e.StatusCode == 429 && e.RetryAfter is { } retryAfter)
{
    Console.WriteLine($"rate limited, retry after {retryAfter}");
}
catch (ApiException e) when (e.StatusCode == 429)
{
    Console.WriteLine("monthly request budget spent");
}
catch (ApiException e)
{
    Console.WriteLine($"request {e.RequestId} failed: {e.Detail ?? e.Title}");
}
catch (ApiConnectionException e)
{
    Console.WriteLine($"no response: {e.Message}");
}

• Transport and decoding: A call that gets no response throws an ApiConnectionException, or its subclass ApiTimeoutException when SynthientClientOptions.Timeout or the default handler's 10-second connect timeout elapses. A response the SDK cannot decode throws a SynthientException, the base type of all of them.
• Cancellation: Cancelling a call's token throws OperationCanceledException.
• Response hook: An exception thrown by ResponseHook fails the call unchanged.
• Before a request: Invalid arguments, such as an IPv6 address with a scope ID or a malformed export ID, throw an ArgumentException before any request is sent.
• Disposal: Calls on a disposed client throw ObjectDisposedException. See Dispose.

See Errors for what each status means.

SynthientException

The base type of the exceptions the SDK throws for failed API calls.

public class SynthientException : Exception
public SynthientException(string message)
public SynthientException(string message, Exception? innerException)

• Thrown when: It is thrown directly when the API returns a response the SDK cannot use, such as a malformed body, a body or stream event larger than 16 MiB, or an export listing that repeats a cursor.

ApiException

The API returned an error status.

public sealed class ApiException : SynthientException
public ApiException(int statusCode, Exception? innerException = null)

• Logging: Message holds only the status, such as 403 Forbidden, so it is safe to log.
• Untrusted fields: The other properties contain untrusted server data and can include sensitive information, so inspect them explicitly.
• Unwrapping: InnerException is the exception that interrupted reading the error body, if any.
• Testing: The constructor is public so applications can stub the SDK in their own tests, and the other properties can be set with an object initializer.

ApiConnectionException

No response arrived: the connection failed or was closed, or reading the response failed.

public class ApiConnectionException : SynthientException
public ApiConnectionException(string message, Exception? innerException)

• Processing: The server may still have processed the request.
• Unwrapping: InnerException holds the underlying failure.

ApiTimeoutException

SynthientClientOptions.Timeout elapsed while waiting on the network, or the default handler's 10-second connect timeout elapsed.

public sealed class ApiTimeoutException : ApiConnectionException
public ApiTimeoutException(string message, Exception? innerException)

• Cancellation: Cancelling a call's token throws OperationCanceledException instead.

Retries and timeouts

Which calls are retried:

• Account and feed requests are retried on 500, 502, 503, and 504 responses, on 429 responses that carry Retry-After, and when no response arrives because the connection failed (other than a TLS error) or a timeout elapsed: SynthientClientOptions.Timeout while waiting for the response headers, or the default handler's 10-second connect timeout.
• Billed lookups (LookupIPAsync, LookupIPsAsync, and LookupDomainAsync) and CheckHealthAsync are retried only on 429 responses that carry Retry-After, which the rate limiter returns before doing any work, so a lookup is never sent twice after the API may have charged for it.
• A 429 without Retry-After means the key's monthly request budget is spent or it has too many open streams, so it is not retried.
• A failure while reading a response body is never retried.
• Downloads from the export storage host are never retried.

How retries wait:

• Retries back off exponentially from one second, doubling up to 30 seconds, with 25% jitter.
• The wait is never shorter than Retry-After.
• A Retry-After longer than a minute throws the response's ApiException instead of retrying.
• Cancelling the call's token ends the wait.
• Set the retry count with SynthientClientOptions.MaxRetries.

SynthientClientOptions.Timeout, 60 seconds by default, bounds each wait on the network rather than a whole call, so streams and downloads are not cut off. The client's own handler also gives up on a connection attempt after 10 seconds. Bound a whole call with its cancellation token:

using var cancel = new CancellationTokenSource(TimeSpan.FromSeconds(10));
var info = await client.LookupIPAsync(IPAddress.Parse("8.8.8.8"), cancel.Token);
Console.WriteLine(info.IP);