# Errors and troubleshooting

> What initialization failures mean, how to handle them, and common integration issues.

> For AI agents: the complete documentation index is at https://nosmai.com/llms/moderations.txt

Product: Nosmai Moderation
Group: reference
Source: https://nosmai.com/docs/moderations/errors/

## Initialization

`init` / `initialize` reports a failure when the SDK cannot start. The common reasons:

| Reason | What happened | What to do |
| --- | --- | --- |
| Invalid key | The license key is wrong, or not registered for this app and platform | Check that the key, package name or bundle id, and platform match your dashboard |
| Expired license | The license is no longer active | Renew it in the dashboard |
| First launch offline | No cached license yet and the device has no connectivity | Retry once the device is online |
| Grace expired | The device has been offline past the offline grace window | Reconnect to revalidate |

Always check the return value and do not moderate until initialization succeeds. A missing or invalid license means the SDK will not run.

## License error codes

When the licensing service rejects the verify request during `init` / `initialize`, it returns one of these codes. The SDK turns them into an initialization failure, and for a definitive rejection it treats the license as invalid. A `4xx` code means a real key or license problem to fix; `429` is transient, so retry with backoff.

| Code | HTTP | Meaning |
| --- | --- | --- |
| `MISSING_REQUIRED_FIELDS` | 400 | A required field is missing from the request. |
| `API_KEY_INVALID` | 401 | Key not found, wrong, or revoked. |
| `PRODUCT_MISMATCH` | 403 | The key is not a Moderation SDK key. |
| `PLATFORM_MISMATCH` | 403 | The key is for a different platform (iOS vs Android). |
| `PACKAGE_ID_MISMATCH` | 403 | The key is for a different app (package name / bundle id). |
| `LICENSE_EXPIRED` | 403 | The license or subscription has expired. |
| `MAU_LIMIT_EXCEEDED` | 403 | The monthly active user / device limit was reached. |
| `INVALID_SDK_VERSION` | 403 | This SDK version is not allowed. |
| `PROJECT_INACTIVE` | 403 | The project is disabled. |
| `RATE_LIMIT_EXCEEDED` | 429 | Too many requests. Retry with backoff. |

## Text moderation

`initText` / `initializeText` fails if you call it before a successful `init` / `initialize`, since the license must be validated first. Call init, confirm it succeeded, then initialize text.

If your license does not include text moderation, text initialization does not start and `moderateText` returns a safe result.

## Empty or always-safe results

- **Everything is safe.** Confirm initialization succeeded. If it failed, every check is treated as safe.
- **A category never appears.** Confirm that category is included in your license. Categories outside your plan are never reported.
- **A moderation type does nothing.** Confirm that type (image, video, text or live) is included in your license.

## Live camera

- **No results.** Make sure you started the stream and that camera permission is granted.
- **Rotated or sideways frames.** Pass the correct rotation when you push frames (see the platform guide).
- **Preview stutters on weak devices.** Push a sampled subset of frames (for example every Nth frame) and do the pixel conversion off the capture thread.
- **Camera or video playback conflicts after leaving a moderation screen on iOS.**
  Stop the screen's capture session and call `suspendVisualModeration()`. In
  React Native, pass the navigation focus state to the preview's `active` prop.

## Platform notes

- **Android.** The SDK ships `arm64-v8a` only. Distribute as an App Bundle so 32-bit-only devices and x86_64 emulators are handled correctly, and test on a physical arm64 device.
- **iOS.** Set `ITSAppUsesNonExemptEncryption` to `NO` in `Info.plist` so App Store and TestFlight uploads are not blocked on the encryption question.