Virtneu Auth Docs

Troubleshooting

Diagnose common API failures, preserve idempotency, and correlate requests.

Check the response

Status or errorWhat to check
401Check the server key or the user's credentials, according to the returned error code.
403Verify the key scope, app ID, and environment.
409Compare the original request and the retry. For revision conflicts, read the latest value before merging your change.
429Honor Retry-After before starting another attempt.
503The service could not complete the request. Session validation and account-access checks must deny the current request while preserving the distinction from active: false. Do not permanently revoke a business credential because of an outage.
RESOURCE_NOT_FOUNDFor user lookup or detail, the identity does not exist in the selected app and environment. Batch reads report missing IDs in missing_user_ids instead.
INVALID_USER_CURSORRestart user listing without a cursor. Keep the same app, environment, key, filters and sort across pages.
APPLICATION_STATE_CHANGEDThe environment lifecycle changed during the request. Re-establish the current app/environment state before retrying.
MAIL_NOT_CONFIGUREDCall SDK getMailReadiness() or MCP get_mail_readiness; follow its settings_url to configure, test and enable email for that App/environment. Routing/API-key success alone does not establish mail readiness.
PASSWORD_AUTH_DISABLEDUse email-code authentication, or have an authorized Studio member enable password authentication for the selected environment.
METADATA_CONFLICTRead the latest objects and revision before merging and saving again.
INVALID_METADATASupply the exact required fields, a nonnegative integer revision, and JSON objects within the per-object UTF-8 limit.
REAUTHENTICATION_REQUIREDStart a new authentication flow. The prior operation's encrypted result is no longer recoverable.
MAIL_DELIVERY_UNKNOWNCheck delivery before starting another send. Cloudflare delivery with an unknown outcome stops automatic resending.

Retry a write safely

On NETWORK_ERROR or REQUEST_TIMEOUT, the server may already have accepted the request. Authentication operations have a 60-second recovery window. Reuse the original idempotency key and payload during that window. OPERATION_PENDING and MAIL_DELIVERY_PENDING can also be retried with that same key during the window. If recovery expires, start a new authentication flow. Check required headers and inputs in the OpenAPI contract.

For password sign-in, 429 RATE_LIMITED means the failed or in-flight attempt budget is exhausted. Wait for Retry-After, then start a new logical attempt with a new key. Successful sign-in releases its own reservation. The budget is 10 attempts per identity, app and environment in a 10-minute window.

Metadata replacement uses its current revision. After a timeout, read the value again and compare it with the intended update before saving against the latest revision. See Metadata for complete-object replacement and field mapping.

The SDK exposes VAuthError fields including code, status, retryable, requestId, and retryAfterSeconds. Keep API keys, passwords, tokens, and request bodies out of logs.

If SDK user-query methods are missing or metadata payloads fail after an SDK upgrade, run npm install @virtneu/auth in your backend project and check the SDK compatibility notes. Use profile_metadata and managed_metadata; old payload aliases are not accepted. Direct HTTP integrations must send X-Virtneu-Auth-Application and X-Virtneu-Auth-Environment. A key without the newly required users:read / users:status scope must be replaced with a suitably scoped key.

Find a request

Keep the response's X-Request-Id or request_id when investigating an error. Each HTTP attempt has its own request ID. With auth-events:read, call listAuthenticationEvents({ request_id }) or open Authentication events from the environment menu in Studio.

On this page