Errors and responses
Handle typed Swift results, HTTP failures, timeouts, and decoding errors.
Successful SDK calls return a concrete response model; failures are thrown as ApiError. There is no nullable success wrapper to unwrap use Swift's normal do/catch control flow around each awaited operation.
Handle failures
do {
let response = try await client.retrieveARecord(recordId: recordID)
print(response.data.name)
} catch let error as ApiError {
switch error {
case .httpError(let httpError):
print(httpError.statusCode)
print(httpError.kind)
print(httpError.body?.message ?? httpError.localizedDescription)
case .timeout(let underlying):
print("Timed out", underlying?.localizedDescription ?? "")
case .networkError(let underlying):
print("Network failure", underlying.localizedDescription)
case .encodingError(let underlying), .decodingError(let underlying):
print("Serialization failure", underlying.localizedDescription)
case .invalidURL, .invalidResponse:
print(error.localizedDescription)
}
}ApiError cases
| Case | Meaning | Typical action |
|---|---|---|
.httpError(HTTPError) | Insion returned a non-success HTTP response. | Inspect status, kind, and optional body; correct the request or retry only when appropriate. |
.timeout(Error?) | The request exceeded its timeout. | Retry only if the operation and your workflow are safe to retry; adjust timeout if justified. |
.networkError(Error) | The transport failed before a valid response. | Treat as a connectivity failure and apply your retry/backoff policy. |
.encodingError(Error) | The SDK could not encode a request. | Check the model and custom JSON data passed to the SDK. |
.decodingError(Error) | A successful response could not be decoded. | Record enough diagnostics to investigate the response shape. |
.invalidURL / .invalidResponse | The endpoint URL or returned HTTP response was invalid. | Check base URL configuration and report unexpected server behavior. |
HTTP errors
HTTPError exposes statusCode, kind, and a best-effort body. The body includes code, optional type, and optional message; it can be decoded from a structured payload, a JSON message, or plain text.
The SDK classifies errors as .unauthorized (401), .forbidden (403), .notFound (404), .validation (422), .serviceUnavailable (503), plus redirect, other client, server, and other categories. This lets application code distinguish a bad token from a missing record or a temporary server issue without comparing raw integers everywhere.
Response models and Nullable
Responses use native Swift types and strongly typed models. Some API fields use Nullable<T> rather than T?: that wrapper preserves the distinction between a JSON null and a value. Do not assume a field with Nullable has a non-null payload; branch according to the wrapper before using it. Fields declared as T? may also be absent entirely.
For lists, inspect both data and hasMore. A non-empty page is not proof that the full collection has been returned; use the last item's Insion id as a cursor when hasMore is true.