Error Handling & Localizer
Relevant source files
The following files were used as context for generating this wiki page:
The Error Handling & Localizer system in the put.io iOS application provides a unified mechanism for transforming technical API and system errors into user-friendly, localized messages. It decouples the raw error data received from the SDK or system services from the presentation layer, allowing for consistent error reporting and recovery suggestions across different features like Authentication, Settings, and File Management.
The core of this system is the APIErrorLocalizer, which uses pattern matching against status codes and error types to select the appropriate localized copy. This ensures that users receive actionable instructions (e.g., "Please check your internet connection") rather than cryptic technical codes. Sources: Putio/Common/API/PutioSDK+ErrorLocalizer.swift, PutioTests/APIErrorLocalizerTests.swift
Architecture and Components
The error handling architecture relies on a protocol-oriented approach where errors are mapped to a structured PutioLocalizedError.
Key Data Structures
| Type | Description |
|---|---|
PutioLocalizedError | A container for the user-facing message, a recovery suggestion, and the original underlying error. |
PutioLocalizedErrorRecoverySuggestion | An enum that can either be a simple instruction or a specific action with a trigger callback. |
APIErrorLocalizer | A struct that contains a matcher (status code or error type) and a closure to perform the localization. |
PutioErrorLocalizableInput | A protocol that ensures an error object provides a localizerType and localizerMessage. |
Sources: Putio/Common/API/PutioSDK+ErrorLocalizer.swift:3-70
Logic Flow
The system matches incoming errors against a list of localizers. If a specific localizer matches the HTTP status code or the string-based error type, it is used; otherwise, the system falls back to a generic "Something went wrong" message.
Localization Mapping
The application defines several standard localizers for common network and API scenarios.
Standard Localizers
- Network Error: Matches status code
0. Provides message "Network error" and suggests checking the internet connection. - Unknown Error: Fallback localizer for decoding failures or 500-range server errors.
- Auth Localizers: Specific mappings for 401 Unauthorized errors and various Two-Factor Authentication (2FA) failures like
invalid_codeorcode_not_found.
Sources: Putio/Common/API/PutioSDK+ErrorLocalizer.swift:72-83, Putio/Features/Auth/AuthErrors.swift:6-45
Auth-Specific Error Handling
The AuthErrors utility extends the base localizer to handle complex authentication flows, mapping multiple server-side error strings to a singular "The code you entered is invalid" user message for 2FA.
Sources: Putio/Features/Auth/AuthErrors.swift:18-46
Presentation Layer Integration
Errors are presented to the user primarily through UIAlertController or specialized state-based views (e.g., in FilesViewController).
Sequence of Error Presentation
When a network request fails, the following sequence occurs to present the error:
Internal Failures
For errors that are not meant for the end-user but require developer attention, the InternalFailurePresenter is used. This is particularly prevalent in database operations (Realm) and deep link handling where a failure indicates a logical inconsistency rather than a user-serviceable issue. Sources: Putio/Common/Helpers/InternalFailurePresenter.swift, Putio/Common/Helpers/Realm.swift:45-53
Persistence and Database Errors
The system also handles infrastructure-level errors, specifically regarding the Realm database.
- Incompatible Schema: If Realm cannot upgrade a file format (e.g., from version 9 to 10), it logs a warning, deletes the old database, and sets a recovery flag.
- Write Failures: The
PutioRealmwrapper catches write exceptions and logs them with context strings to assist in debugging.
Sources: Putio/Common/Helpers/Realm.swift:77-101
Conclusion
The Error Handling & Localizer module provides a robust, testable framework for managing failure states. By centralizing localization logic in APIErrorLocalizer, the project ensures that technical errors are consistently translated into meaningful user guidance, while InternalFailurePresenter maintains diagnostic visibility for non-recoverable system states.