Guide
Errors and Status Handling
Stable documented SoundSync plugin licensing and Test Connection errors, retry guidance, lock behavior, and offline-grace implications.
SoundSync
Documented codes
These codes are verified in the contract catalog. Do not treat hard denials as offline-grace events.
| Code | HTTP | Meaning | Recommended action | Grace? |
|---|---|---|---|---|
| MISSING_CREDENTIALS | 400 | Test Connection body is missing productId, appId, pluginKey, or pluginSecret. | Fix request. Do not retry blindly. | No |
| INVALID_APP_ID | 401 | The App ID does not identify an active product credential row. | Use the App ID from the product credential panel or generated package. | No |
| INVALID_PLUGIN_KEY | 401 | Plugin key hash mismatch for the App ID. | Use the current plugin key; regenerate package after rotation. | No |
| INVALID_PLUGIN_SECRET | 401 | Plugin secret hash mismatch for the App ID. | Use the current secret. Do not ask customer for it. | No |
| REVOKED_CREDENTIAL | 403 | Credential was revoked. | Regenerate/rotate credentials and package config. | No |
| PRODUCT_MISMATCH | 403 | Credential belongs to a different product than productId. | Do not mix product config files. | No |
| SERIAL_NOT_FOUND | 404 | Serial/license key was not found. | Ask customer to check key or contact support. | No |
| SERIAL_PRODUCT_MISMATCH | 403 | Serial belongs to another product. | Check productId/app credentials and serial source. | No |
| CUSTOMER_DETAILS_REQUIRED | 200 | Serial requires customer identity before activation. | Open claim flow and collect email/customer details. | No |
| PENDING_EMAIL_VERIFICATION | 200 | Claim exists but customer has not completed email verification. | Keep activation UI open and poll/resume claim-status. | No |
| CLAIM_ACTIVATION_TOKEN_INVALID | 403 | Verified-claim activation token is invalid or expired. | Restart claim flow if still eligible. | No |
| SERIAL_ACTIVATION_LIMIT_REACHED | 409 | Device limit is reached. | Show device-management/support path. | No |
| subscription_payment_required | 402 | Subscription is past due after payment grace. | Lock access and route to billing/support. | No |
| subscription_incomplete | 402 | Subscription checkout is incomplete. | Keep locked until checkout completes. | No |
| subscription_inactive | 403 | Subscription is canceled, unpaid, or expired. | Lock access and route to support/billing. | No |
| device_not_activated | 401 | Validation found no activation for this machine. | Clear invalid local state and require activation. | No |
| device_deactivated | 401 | This activation was deactivated. | Clear local state and require reactivation. | No |
Implementation-defined or under review
Any code not listed here should be displayed as an implementation-defined failure with sanitized diagnostics. Do not invent customer-facing copy for undocumented codes without adding it to the contract catalog first.