> ## Documentation Index
> Fetch the complete documentation index at: https://idp-docs.facesign.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Concrete errors from the SSO endpoint and the verification flow, and what each one means.

## SSO endpoint errors

Every failure at `/api/saml/sso` returns JSON with a stable `code`. The human `error` string may
change; branch on `code`.

<AccordionGroup>
  <Accordion title="unregistered_sp — 400">
    The `<Issuer>` in your AuthnRequest does not exactly match a registered entityID.

    Matching is an exact, case-sensitive string comparison. The most common cause is a trailing
    slash, `http` versus `https`, or a hostname that differs from what was registered. Check the
    value your SP actually sends on the wire, not what its config screen displays.
  </Accordion>

  <Accordion title="subject_echo_disabled — 400">
    Your AuthnRequest carried a `<Subject>` NameID, but your service provider is not registered
    for Subject echo.

    Echo is off by default and granted only to explicitly registered, isolated, non-authorizing
    sandbox SPs. Either omit the `<Subject>` — you will get a transient
    `facesign-session:<sessionId>` NameID instead — or ask FaceSign to enable echo for your exact
    registration. See [NameID echo](/saml-request-contract#nameid-echo) for why this gate exists.
  </Accordion>

  <Accordion title="unsupported_request — 400">
    Most often a signed AuthnRequest. Request signing is not supported in this release, and the metadata declares
    `WantAuthnRequestsSigned="false"`. Configure your SP to send unsigned requests.
  </Accordion>

  <Accordion title="invalid_request — 400">
    The AuthnRequest was structurally unacceptable — a malformed `<Subject>`, an unsupported
    NameID format, a NameID containing control or invisible characters, or a NameIDPolicy that
    cannot be satisfied.
  </Accordion>

  <Accordion title="destination_mismatch / acs_mismatch — 400">
    The `Destination` does not match the SSO endpoint, or the ACS URL in the request does not
    match the one registered for your entityID. Re-import the metadata and re-check your
    registered ACS.
  </Accordion>

  <Accordion title="rate_limited — 429">
    You exceeded the session-creation limits: 20 per minute per IP and SP, 120 per minute per
    SP. Load tests hit the per-SP limit first. A `Retry-After` header is included.
  </Accordion>

  <Accordion title="malformed_request / request_too_large — 400">
    The SAMLRequest could not be decoded, or exceeded the size limit. Check your binding: the
    HTTP-Redirect binding expects DEFLATE-compressed base64, HTTP-POST expects uncompressed
    base64. Sending one as the other produces this.
  </Accordion>
</AccordionGroup>

## The verification did not pass

A refusal is a signed, status-only `Responder` with nested `AuthnFailed` and no assertion. That
is a correct, authentic message — your SP should reject the login while still accepting the
response as genuine.

Common causes, in rough order of frequency:

| What happened                     | What the person experienced                                                                        |
| --------------------------------- | -------------------------------------------------------------------------------------------------- |
| No face detected                  | The camera could not see a face. The avatar asks once to recenter, then retries once.              |
| Intent declined                   | They answered no, or indicated pressure or reluctance. This is a duress signal, not a malfunction. |
| No clear confirmation             | The conversation reached two exchanges with no clear yes or no.                                    |
| Session abandoned                 | They closed the tab or walked away.                                                                |
| Analysis did not complete in time | A FaceSign-side issue, not a statement about the person.                                           |

<Note>
  Those last two are not the person's fault, but today they arrive on the wire looking identical
  to a genuine refusal. A status taxonomy that separates them is not available in this release. If your fallback
  policy needs to distinguish "they failed" from "we could not check", raise it before you build.
</Note>

## Sign-in and portal problems

<AccordionGroup>
  <Accordion title="Sign-in to the partner portal fails">
    The portal sign-in page shows a reference code on any failure. Quote it — it resolves to the
    exact cause in our logs.

    The most common cause is starting sign-in in one browser window and finishing it in another,
    or taking longer than ten minutes over a password reset. Start fresh at
    [the portal](https://idp.facesign.dev/portal) and complete it in one pass, in the same window.
  </Accordion>

  <Accordion title="The camera never starts">
    Check the browser has camera permission for the FaceSign session domain, and that no other
    application holds the camera. A phone is generally more reliable than a desktop webcam.
  </Accordion>
</AccordionGroup>

## Still stuck

Email [partnerships@facesign.ai](mailto:partnerships@facesign.ai?subject=FaceSign%20SAML%20IdP%20—%20troubleshooting)
with your entityID, the approximate time, and the `code` you received. If you have a
`facesign.sessionId` from a response, include it — it is the fastest correlation key we have.

Check [service health](https://idp.facesign.dev/api/health) first: it verifies that the IdP can
generate metadata and that its signing key matches the advertised certificate. It does not run
an end-to-end verification, so a green health check does not promise a round-trip will succeed.