SSO endpoint errors
Every failure at/api/saml/sso returns JSON with a stable code. The human error string may
change; branch on code.
unregistered_sp — 400
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.subject_echo_disabled — 400
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 for why this gate exists.unsupported_request — 400
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.invalid_request — 400
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.destination_mismatch / acs_mismatch — 400
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.rate_limited — 429
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.malformed_request / request_too_large — 400
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.
The verification did not pass
A refusal is a signed, status-onlyResponder 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:
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.
Sign-in and portal problems
Sign-in to the partner portal fails
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 and complete it in one pass, in the same window.
The camera never starts
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.
Still stuck
Email partnerships@facesign.ai with your entityID, the approximate time, and thecode you received. If you have a
facesign.sessionId from a response, include it — it is the fastest correlation key we have.
Check service 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.