Docs / Refusal codes
Refusal codes
Every refusal from POST /v1/verify/ carries a machine-readable
PG_* reason code. Codes are classified hard — no retry,
reshaped request, or replacement license changes the outcome — or
soft: a different request, a valid license, or a different provider
might still succeed. An unregistered code fails closed (treated as hard), never
silently retryable.
| Code | Category | Type | Since | Meaning |
|---|---|---|---|---|
| PG_MISSING_PROMPT_HASH | request | soft | 2025-01-01 | The request did not include a prompt_hash to bind the decision to. |
| PG_NO_PAIR | identity | soft | 2025-01-01 | No live provider↔licensee pair authorizes this caller. |
| PG_IDENTITY_REVOKED | identity | HARD | 2025-06-01 | The provider disowned this end user’s identity link. |
| PG_ENTITLEMENT_INACTIVE | identity | HARD | 2025-06-01 | The purchase (entitlement) backing this request is no longer active — reversed or expired. |
| PG_PROVIDER_NOT_ALLOWED | identity | soft | 2025-06-01 | This license’s allow/block list excludes the calling provider. |
| PG_IDENTITY_UNKNOWN | identity | soft | 2026-07-26 | The asserted end-user identity does not resolve to any live identity link for this provider — the user has not completed the connect flow, or the link was deleted. |
| PG_IDENTITY_MISMATCH | identity | soft | 2026-07-26 | The license belongs to a different end user than the one the caller is acting for — cross-user reuse. |
| PG_IDENTITY_REQUIRED | identity | soft | 2026-07-26 | The license is bound to a specific end user, so the caller must say which user it is acting for. |
| PG_NO_SUBJECT | subject trust | soft | 2025-01-01 | No registered subject matches subject_id. |
| PG_SUBJECT_OPTED_OUT | subject trust | HARD | 2025-01-01 | The subject’s rules refuse this request’s category outright. Checked before any license — no license can override it. |
| PG_SUBJECT_DISPUTED | subject trust | HARD | 2025-09-01 | A dispute is open on this subject — licensing is frozen pending outcome. |
| PG_SUBJECT_WITHDRAWN | subject trust | HARD | 2025-01-01 | The subject was withdrawn by its owner or on moderation takedown. |
| PG_SUBJECT_PENDING | subject trust | soft | 2025-01-01 | The subject is awaiting operator review before it may license at all. |
| PG_SUBJECT_PAUSED | subject trust | soft | 2025-01-01 | The subject’s owner temporarily paused licensing. |
| 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_REFERENCE_ONLY | subject trust | HARD | 2025-01-01 | The subject is registered as reference-only and never licenses. |
| PG_PROVIDER_VETOED | subject trust | HARD | 2025-07-01 | The rights holder blocked this specific provider — no license changes that. |
| PG_SANDBOX_SUBJECT_ONLY | subject trust | HARD | 2025-08-01 | A sandbox (Tier 1) provider credential may only verify against synthetic test subjects. |
| PG_PROHIBITED_USE | subject trust | HARD | 2026-06-01 | A permanently-denied use for a high-risk subject — e.g. a sexualized category for a minor. |
| PG_INSUFFICIENT_AUTHORITY | subject trust | soft | 2025-10-01 | The subject’s authority/verification tier does not meet the bar this request needs. |
| PG_OWNER_NOT_VERIFIED | subject trust | soft | 2026-08-19 | Commercial use also requires the subject’s owning account to be verified — the subject alone reaching commercial status is not sufficient. |
| PG_NO_LICENSE | license | soft | 2025-01-01 | No valid, live license authorizes this licensee for this subject. |
| PG_INVALID_SIGNATURE | license | HARD | 2025-01-01 | A license was found but its signature does not verify. |
| PG_SCOPE_VIOLATION | license | soft | 2025-01-01 | The request’s modality, channel, or territory falls outside what the license scopes. |
| 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_MISSING_CONTEXT | license | soft | 2025-04-01 | The license restricts a dimension and the request omitted it — fail-closed rather than let an omission bypass a restriction. |
| PG_IMMUTABLE_DENIAL | license | HARD | 2025-01-01 | The request’s declared category matches one of the license’s immutable (never-grantable) denials. |
| PG_TIER_VIOLATION | license | soft | 2025-05-01 | The declared use case ranks above what this license’s tier authorizes. |
| PG_EXTENSION_REFUSED | license | soft | 2025-05-01 | A license extension (e.g. a region rider) evaluated and refused this request. |
| PG_REGION_BLOCKED | license | soft | 2025-06-01 | The request’s territory falls outside the license’s allowed regions. |
| PG_LICENSE_REVOKED | license | HARD | 2025-09-15 | A live revocation (full or partial) withdraws this license. |
| PG_RIGHTS_NOT_GRANTED | license | soft | 2026-06-01 | The request exercises a rights dimension (e.g. model_training) the license never granted. |
| PG_USAGE_LIMIT | license | soft | 2025-05-01 | The license’s purchased quantity (max_uses) is exhausted. Surface this to the buyer as “buy more”, not as an error. |
| PG_CONCURRENCY_LIMIT | license | soft | 2025-05-01 | The license’s concurrent in-flight generation cap is reached. Back off and retry later. |
| PG_HELD_FOR_REVIEW | review | soft | 2026-07-24 | Not a refusal: a commercial generation that would otherwise be allowed is held for human review. Treat as pending, not denied. |
For implementers
A correct client stops retrying on HARD codes and reacts to soft ones
(offer a license-request flow, surface “buy more”, back off on concurrency). Retrying a
withdrawn subject forever is the canonical wrong behavior — the hard/soft split exists
precisely to prevent it.