Errors and troubleshooting

Build handling around the stable code, not the human-readable message. Do not blindly retry 4xx responses; most require correcting identity, configuration, or signing logic.

Administrative credential operations may also report SSO_CREDENTIAL_EXISTS, SSO_CREDENTIAL_NOT_FOUND, or SSO_ENCRYPTION_NOT_CONFIGURED. These are Nanaade administrator/operations concerns, not errors your public portal should attempt to repair.

Data prerequisite response

Missing user data is not an authentication failure and not a licensing failure. Nanaade returns 422 Unprocessable Entity with a stable prerequisite code:

HTTP/1.1 422 Unprocessable Entity
Content-Type: application/json

{
  "success": false,
  "status": "failed",
  "code": "RESUME_REQUIRED",
  "prerequisite": "resume",
  "feature": "job-board.resume-scoring",
  "message": "Add or build your resume before using this feature.",
  "action": {
    "type": "navigate",
    "href": "/dashboard/resume",
    "label": "Add resume"
  }
}

Nanaade's hosted module UI handles this response and presents the correct branded recovery flow. If your portal calls a documented API directly, branch on code, show a human-friendly explanation, and let the user return to the original portal path. Do not retry automatically while the prerequisite remains missing.

Diagnose a signature failure

Verify in this order:

1. Client ID and secret come from the same environment/credential issue.
2. The secret has no accidental whitespace or quotes.
3. Payload is base64url(UTF8(JSON.stringify(assertion))).
4. HMAC message is the encoded payload string.
5. Digest output uses Base64URL, not hexadecimal or standard Base64.
6. The payload is not modified after signing.

Diagnose an origin failure

In browser developer tools, inspect the request's Origin header. Compare only the exact scheme, host, and port to Nanaade configuration. A page URL path is irrelevant; a proxy that rewrites hosts may not be.

Diagnose a membership failure

Confirm the client ID belongs to the expected tenant, the target membership is active when one exists, normalized assertion email matches first binding, and the stable subject has not changed. For JIT tenants, also confirm that first launches include name. A successful login to your own portal proves identity only when your backend—not the browser—creates and signs the assertion.

Contacting support

Provide request ID, UTC timestamp, stable error code, client ID (or last characters), environment, expected destination, and whether the failure affects all users. Never provide the secret, full assertion, signature, session cookie, or user password.