Errors & troubleshooting

Every Valyd error is machine-readable: a stable code string plus an HTTP status, and every response carries an X-Request-Id header — quote it to support (never API keys or tokens). Read the status first (it tells you the category), then the code (the exact cause).

Contacting support

Include: the X-Request-Id header value, the session/event id if relevant, a timestamp, and the endpoint called. Never send API keys, tokens, or the person’s identity data — support will never ask for them.

1. Error shapes

Valyd uses two error shapes: the OIDC protocol endpoints speak standard OAuth 2.0 / OpenID Connect errors, and every other Valyd API uses the Valyd envelope.

OIDC protocol errors

Since 2026-09-18 the OIDC protocol endpoints return standard errors (RFC 6749 §5.2, RFC 6750 §3, RFC 7591 §3.2.2) — error is a string, there is no success/data wrapper, and responses carry Cache-Control: no-store:

Token (POST /api/auth/oidc/token), UserInfo (/api/auth/oidc/userinfo) and Dynamic Client Registration (POST /api/auth/oidc/register):

{ "error": "invalid_grant", "error_description": "Invalid or expired authorization code" }

Authorization (/api/auth/oidc/authorize): once your client_id and redirect_uri are verified, every error is sent back to your redirect_uri (RFC 6749 §4.1.2.1 + RFC 9207):

https://yourapp.com/callback?error=access_denied&error_description=The+user+denied+the+request&state=YOUR_STATE&iss=https%3A%2F%2Fidp.valyd.id

error is one of invalid_request (e.g. missing PKCE code_challenge), unsupported_response_type, invalid_scope, invalid_target (RFC 8707 resource not allowed), access_denied (user pressed Cancel, or a private org app the user isn’t assigned to), login_required / consent_required (prompt=none couldn’t be satisfied), request_not_supported, request_uri_not_supported, or server_error. An unknown client_id or an unregistered redirect_uri is the only case that shows an HTML error page on Valyd instead of redirecting (redirecting there would be an open redirect).

Valyd envelope (all other APIs)

Login / account APIs (/api/auth/... outside /api/auth/oidc/*), the Verify API (/api/v2/...), the hosted-flow, verifications, agent and internal endpoints keep the envelope:

{ "success": false, "data": [], "error": { "code": "invalid_token", "message": "Session expired. Please login again." } }

Verification API (/api/v2/...) errors carry the code in error with check context where relevant.

2. What the HTTP status means

3. Complete code catalog

Generated from the API source — 177 codes. Do not edit by hand; run node scripts/gen-error-catalog.mjs.

4. Troubleshooting the common integration mistakes

State mismatch on the callback. The state on your callback must equal the one you stored before redirecting (the button stores it in the valyd_oidc_state cookie; the SDK transaction carries it). If it differs, the login is forged or expired — restart the flow. Never skip this check.

invalid_grant on token exchange. Authorization codes are single-use and expire in ~2 minutes, and are bound to your client, redirect_uri, and PKCE code_challenge. Exchange immediately, exactly once, with the same redirect_uri you authorized with and the matching code_verifier. Replaying a used code also revokes every token it already produced.

error=invalid_request on the callback. Usually a missing PKCE code_challenge (or code_challenge_method=plain). PKCE S256 is required for every client — use the SDK’s createAuthorizationRequest() or send code_challenge + code_challenge_method=S256.

error=access_denied on the callback. The user pressed Cancel on the consent screen, or the app is a private organization app and the user isn’t assigned to it. Show a friendly “sign-in was cancelled” message and offer to retry.

invalid_client with both Basic and body credentials. Authenticate with one method: client_secret_basic (HTTP Basic) or client_secret_post (client_id + client_secret in the form body). Sending both returns invalid_request.

Redirect URI mismatch. URIs are matched exactly — scheme, host, port, and path. Register every environment’s callback in the Developer Portal.

insufficient_scope on userinfo. OIDC resource calls require the openid scope in the token (HTTP 403, {"error":"insufficient_scope",...} plus a WWW-Authenticate: Bearer header). The SDK and button add it automatically; raw integrations must include it in scope.

Wrong environment host. Each environment has its own IdP host (this documentation’s is idp.valyd.id). A token from one environment never works on another — and the Sign-in button targets whichever host served its script.

Refresh suddenly failing. Refresh tokens rotate on every use. If you replay an old one, every refresh token for that user+client is revoked (theft protection) — persist the newest token atomically, then re-login once.