Reference
Errors
The Swift SDK throws AppNorthError. Server responses use stable error codes for program logic; show a helpful explanation to the user instead of displaying the code alone.
Swift error cases
| Case | Meaning and recovery |
|---|---|
invalidConfiguration(String) | Fix the API URL, public App ID or origin before constructing the client |
invalidIdentityCredential(String) | Obtain a valid credential from your authenticated backend |
invalidResponse | The transport did not return an HTTP response; inspect your transport integration |
network(String) | Connectivity failed; retry with a bounded delay |
server(status:code:fields:) | Inspect the HTTP status, stable code and optional field errors |
decoding(String) | The success response could not be decoded; check SDK/server compatibility and the API base URL |
AppNorthOfflineQueueError separately reports persisted-queue failures. See Offline and cache for storage and replay behavior.
Public API failures
| Code or response | Action |
|---|---|
INVALID_APP_ID, PROJECT_NOT_FOUND | Copy the public App ID from the correct app's installation page |
APP_ID_MISMATCH | Use the same public App ID in the feedback body and query |
INVALID_JSON, UNSUPPORTED_MEDIA_TYPE | Send valid JSON with Content-Type: application/json |
INVALID_IDEMPOTENCY_KEY | Supply a key in the format documented in Limits |
IDEMPOTENCY_CONFLICT | The key was already used for a different payload; preserve the original key for retries and use a new one for a new intent |
INVALID_SCREENSHOT | Validate the image data URL and screenshot limits |
INVALID_PAYLOAD, INVALID_QUERY | Correct the fields or query parameters; do not blindly retry |
ORIGIN_NOT_ALLOWED | Correct the configured origin and app's allowed domain |
IDENTITY_REQUIRED | Supply a credential for an identified-only operation |
INVALID_IDENTITY | Renew the signed credential; check expiry and signing inputs on your backend |
IDENTITY_NOT_CONFIGURED | Configure identity verification for this app on the server |
IDENTITY_EMAIL_MISMATCH | Match the feedback email to the verified identity |
CHAT_DISABLED | Enable the intended chat mode in the app's settings |
FEEDBACK_NOT_FOUND | Treat the private thread as unavailable to this identity |
RATE_LIMITED / HTTP 429 | Wait for Retry-After when provided and reduce parallel requests |
| HTTP 413 | Reduce the request body, screenshot or diagnostics |
| HTTP 5xx | Retry recoverable failures with bounded backoff; investigate persistent failures |
Keep the same idempotency key when retrying the same mutation. Do not change its payload and reuse that key. Private resources can return 404 without disclosing another user's data.
Dashboard and provider errors
UNAUTHORIZED requires a dashboard session; FORBIDDEN requires the appropriate workspace role. FORBIDDEN_ORIGIN rejects a cross-origin mutation. PLAN_REQUIRED indicates unavailable feature access or allowance.
For CREDENTIALS_REJECTED, review provider credentials. For CREDENTIALS_UNREADABLE or ENCRYPTION_NOT_CONFIGURED, the deployment operator must check credential encryption. Never solve these by putting secrets in the client.
See Metadata for stale and partial publication, Price localization for uncertain writes, and Troubleshooting for symptom-based checks.
Report a failure
Record the route, HTTP status, error code, SDK version and correlation ID when available. Public responses can include correlationId; the current Swift server case exposes status, code and fields, not a correlation-ID property. Capture safe response metadata through your transport if you need that identifier.
Do not log identity signatures, API keys, private report bodies or screenshots.