Troubleshooting
Common integrator failure modes when calling Runtime or verifying leases. Prefer typed error code from the Error catalog over free-text scraping.
Quick map
| Symptom | Check first |
|---|---|
| Auth / unknown license | Key normalize rules; wrong env; revoked/rotated key — License Keys |
| Lease / JWS reject | JWKS kid, alg=ES256, typ, expiry, audience — Verify trust |
| Offline / air-gapped deny | Lease exp, trust bundle freshness — Offline · Air-gapped |
| Floating seat denied | Checkout/heartbeat/release sequence — Floating |
| Config apply failed | Fail-closed on bad typ / signature — Runtime configuration |
| Rate limit / retry storm | Honor retryable + backoff from error catalog; do not busy-loop |
Typed degraded | Treat as not allow — Production checklist |
Logging hygiene
Never log full license keys, lease tokens, JWE payloads, or PSP secrets. Mask to public prefix only — Secrets.
When to escalate
If OpenAPI and the error catalog disagree with observed HTTP status, capture correlationId (no secrets) and open a support ticket with environment + SDK version (SDKs).