Refusal codes
Core codes are used by every registry with this meaning (spec §3). The rest are the origin registry’s own (PRAMPTA); another registry’s own codes carry its issuer prefix, PG_<ISSUER>_….
Every decision from POST /v1/verify/ carries a reason. A hard code means no retry, reshaped request or new licence changes the answer. A soft code means a different request, a valid licence or a different provider might succeed. An unknown code must be treated as hard.
Two codes are not refusals: PG_STD_TRACKING_ONLY comes with not_blocked (personal use, nothing granted) and PG_ORG_INTERNAL_USE with allow.
| Code | Core | Category | Type | Since | Meaning |
|---|---|---|---|---|---|
| PG_MISSING_PROMPT_HASH | core | request | soft | 2025-01-01 | The request did not include a prompt_hash to bind the decision to. |
| PG_ENTITLEMENT_INACTIVE | identity | hard | 2025-06-01 | The purchase (entitlement) backing this request is no longer active — reversed or expired. | |
| PG_IDENTITY_MISMATCH | identity | soft | 2026-07-26 | The licence belongs to a different end user than the one the caller is acting for — cross-user reuse. Also raised when a request supplies both a link id and a provider user id that describe different people. | |
| PG_IDENTITY_REQUIRED | identity | soft | 2026-07-26 | The licence is bound to a specific end user, and REQUIRE_PROVIDER_USER_BINDING is on, so the caller must say which user it is acting for. Supply provider_user_id or provider_identity_link_id. | |
| PG_IDENTITY_REVOKED | identity | hard | 2025-06-01 | The provider disowned this end user's identity link (Identity v2 §7). | |
| PG_IDENTITY_UNKNOWN | identity | soft | 2026-07-26 | The caller asserted an end-user identity that does not resolve to any live identity link for this provider — the user has not completed the PRAMPTA connect flow, or the link was deleted. | |
| PG_NO_PAIR | core | identity | soft | 2025-01-01 | No live provider↔licensee pair authorizes this caller. |
| PG_PROVIDER_NOT_ALLOWED | identity | soft | 2025-06-01 | This license's allow/block list excludes the calling provider. | |
| PG_INSUFFICIENT_AUTHORITY | subject trust | soft | 2025-10-01 | The subject's authority/verification tier does not meet the bar this request needs. | |
| PG_NO_SUBJECT | core | subject trust | soft | 2025-01-01 | No registered subject matches subject_id. Not a prohibition: this registry knows nothing about the subject, so the provider decides under its own policy and must not present the output as licensed (spec P-5). |
| PG_OWNER_NOT_VERIFIED | subject trust | soft | 2026-08-19 | Commercial use also requires the subject's owning account itself to be verified (identity-verified user, or domain/kyc-tier organization) — the subject alone reaching commercial_enabled is not sufficient. | |
| PG_PROHIBITED_USE | core | subject trust | hard | 2026-06-01 | A permanently-denied use for a high-risk subject (16.9) — e.g. a sexualized category for a minor. |
| PG_PROVIDER_VETOED | subject trust | hard | 2025-07-01 | The rights holder blocked this specific provider — no license changes that. | |
| PG_REFERENCE_ONLY | subject trust | hard | 2025-01-01 | The subject is registered as reference-only and never licenses. | |
| PG_SANDBOX_SUBJECT_ONLY | subject trust | hard | 2025-08-01 | A sandbox (Tier 1) provider credential may only verify against synthetic test subjects. | |
| PG_SUBJECT_DISPUTED | core | subject trust | hard | 2025-09-01 | A dispute is open on this subject (A5, §9) — licensing is frozen pending outcome. |
| PG_SUBJECT_NOT_LICENSABLE | subject trust | hard | 2025-10-01 | The subject's trust-lifecycle state (suspended/disputed/revoked/archived) permits no licensing at all. | |
| PG_SUBJECT_OPTED_OUT | core | subject trust | hard | 2025-01-01 | The subject's rules_text refuses this request's category outright. |
| PG_SUBJECT_PAUSED | core | subject trust | soft | 2025-01-01 | The subject's owner temporarily paused licensing. |
| PG_SUBJECT_PENDING | core | subject trust | soft | 2025-01-01 | The subject is awaiting operator review before it may license at all (reserved/high-profile name). |
| PG_SUBJECT_WITHDRAWN | core | subject trust | hard | 2025-01-01 | The subject was withdrawn by its owner or on moderation takedown. |
| PG_CONCURRENCY_LIMIT | license | soft | 2025-05-01 | The license's concurrent in-flight generation cap is reached. | |
| PG_EXTENSION_REFUSED | license | soft | 2025-05-01 | A license extension (e.g. a region rider) evaluated and refused this request. | |
| PG_IMMUTABLE_DENIAL | core | license | hard | 2025-01-01 | The request's declared category matches one of the license's immutable (never-grantable) denials. |
| PG_INVALID_SIGNATURE | core | license | hard | 2025-01-01 | A license was found but its signature does not verify. |
| PG_LICENSE_REVOKED | core | license | hard | 2025-09-15 | A live revocation (full or partial — this provider/modality/channel/region) withdraws this license (A7). |
| PG_MISSING_CONTEXT | license | soft | 2025-04-01 | The license restricts a dimension (modality/channel/territory/use case) and the request omitted it — fail-closed rather than let an omission bypass a restriction. | |
| PG_NO_LICENSE | core | license | soft | 2025-01-01 | No valid, live license authorizes this licensee for this subject. |
| PG_PRODUCT_MISMATCH | license | soft | 2025-04-01 | The license is bound to a specific product and this request names a different one. | |
| PG_PROJECT_MISMATCH | license | soft | 2025-04-01 | The license is bound to a specific project and this request names a different one. | |
| PG_REGION_BLOCKED | license | soft | 2025-06-01 | The request's territory falls outside the license's allowed regions (Identity v2 scope). | |
| PG_RIGHTS_NOT_GRANTED | license | soft | 2026-06-01 | The request exercises a rights dimension (16.8 — e.g. model_training) the license never granted. | |
| PG_SCOPE_VIOLATION | core | license | soft | 2025-01-01 | The request's modality, channel, or territory falls outside what the license scopes. |
| PG_TIER_VIOLATION | license | soft | 2025-05-01 | The declared use case ranks above what this license's tier authorizes. | |
| PG_USAGE_LIMIT | core | license | soft | 2025-05-01 | The license's purchased quantity (max_uses) is exhausted. |
| PG_ORG_INTERNAL_USE | grant | soft | 2026-09-25 | ALLOWED without a licence: the connected user is an owner, admin or creator of the organization that itself holds this character, brand or work (never a person's likeness or voice). Ends when they leave the organization or lose the role. core/authz.py::org_internal_user. | |
| PG_HELD_FOR_REVIEW | core | review | soft | 2026-07-24 | A commercial generation of a high-risk subject that would otherwise be ALLOWED is held for a human (opt-in, REVIEW_HIGH_RISK_COMMERCIAL). |
| PG_STD_TRACKING_ONLY | core | tracking | soft | 2026-09-21 | Personal use with no licence: the fixed floor (opt-out, status, minors, scope, deny) passed, so PRAMPTA does not block it — but grants nothing. disposition=not_blocked. |
A correct client stops on hard codes and reacts to soft ones: offer a licence request, show “buy more”, back off on concurrency. Retrying a withdrawn subject forever is the canonical wrong behaviour.