Reason codes explain why an action is blocked, restricted, or unavailable.
Use the reason code to choose the next action. Do not retry a blocked action unless the underlying state has changed.
Common Reason Codes
NO_CONSENT
The user has not granted the required permission. Request consent for the specific action.
CONSENT_EXPIRED
The permission expired. Ask the user to renew access only if the action still requires it.
APP_NOT_VERIFIED
The app does not have the required review status. Complete app review or remove the restricted feature.
INSUFFICIENT_TRUST
The account or app does not meet the trust requirement. Show the required step instead of continuing.
THREAD_BLOCKED
The conversation cannot receive app messages. Stop sending and respect the blocked state.
THREAD_CLOSED
The conversation is closed. Use an approved recovery path if one exists.
FEATURE_GATED
The capability is not enabled for the partner, user, market, or environment.
Error Handling
Partner apps should:
- read the code
- read the message
- check the current state
- show the required action
- stop unsafe retries
- log enough context for diagnosis
Do not expose sensitive payloads to end users.
Recovery Paths
A recovery path should match the reason.
For example:
- request consent for missing consent
- renew access for expired consent
- complete app review for app verification
- remove unavailable actions for gated features
- stop sending when a thread is blocked
Generic retry buttons create noise and do not fix policy state.
Partner Logs
Logs should help your team diagnose the issue without storing sensitive account data.
Avoid logging tokens, identity documents, private verification material, wallet secrets, full message payloads unless required for the approved service, or private Onyx account details.