Error Reference

This page documents every error response you may encounter when integrating with UniAuth. Understanding error formats, status codes, and troubleshooting steps will help you build robust integrations that handle edge cases gracefully.

Error Response Formats

UniAuth uses two distinct error response formats depending on the API surface. All error responses include a Content-Type: application/json header.

Authentication and User APIs

Endpoints under /api/auth/* and /api/user/* return errors in the following format:

{
  "success": false,
  "message": "Invalid email or password"
}

The success field is always false for error responses, and the message field contains a human-readable description of what went wrong. Some endpoints may include additional fields such as field (indicating which input failed validation) or remaining (for lockout timing).

OAuth2 and OIDC APIs

Endpoints under /api/oauth/* follow the OAuth 2.0 error response format defined in RFC 6749 Section 5.2:

{
  "error": "invalid_grant",
  "error_description": "Authorization code has expired"
}

The error field is a machine-readable error code from a predefined set (see the OAuth2 Error Codes table below). The error_description field provides additional context for developers. Your application should branch on the error code, not the description text, as descriptions may change.

HTTP Status Codes

The following table summarizes the HTTP status codes returned by UniAuth APIs and their typical causes:

OAuth2 Error Codes

The following error codes may be returned by OAuth2 endpoints ( /api/oauth/token, /api/oauth/authorize, /api/oauth/revoke, /api/oauth/introspect):

Rate Limit Errors (429)

When you exceed the rate limit for an endpoint, UniAuth returns a 429 Too Many Requests response. The response includes a Retry-After header indicating how many seconds to wait before making another request.

HTTP/1.1 429 Too Many Requests
Retry-After: 900
Content-Type: application/json

{
  "success": false,
  "message": "Too many requests. Please try again later."
}

Rate limits are enforced per IP address within a sliding window. Different endpoints have different limits. Sensitive endpoints like login and registration have stricter limits to prevent brute-force attacks. See the Rate Limits page for the full table of per-endpoint limits.

Account Lockout Behavior

UniAuth implements progressive account lockout to protect against brute-force password attacks. After multiple consecutive failed login attempts, the account is temporarily locked. The lockout duration increases with each threshold:

When an account is locked, the login endpoint returns a 401 Unauthorized response with a generic invalid credentials message. This is intentional — returning a distinct status code or lockout details would allow attackers to enumerate which accounts exist.

HTTP/1.1 401 Unauthorized
Content-Type: application/json

{
  "success": false,
  "message": "Invalid credentials"
}

The response is deliberately identical to a normal failed login to prevent account enumeration. The lockout counter resets automatically upon a successful login. Users can also bypass the lockout by authenticating with a passkey, as passkey authentication does not rely on the password.

Troubleshooting Common Errors

The following table covers the most frequently encountered errors during integration and how to resolve them:

Error Handling Best Practices

• Always check the HTTP status code first. Use the status code to determine the category of error before parsing the response body.
• Branch on error codes, not messages. For OAuth responses, use the error field for control flow. Error descriptions are informational and may change.
• Implement retry logic for transient errors. Status codes 429 and 500 are candidates for retry with exponential backoff. Do not retry 400, 401, 403, or 409 errors as they indicate a problem with the request itself.
• Log error responses for debugging. Include the full response body, status code, and request details in your application logs. This is invaluable when diagnosing integration issues.
• Show user-friendly messages. Never display raw error responses to end users. Map error codes to human-friendly messages in your application's language.
• Handle token refresh proactively. Rather than waiting for a 401 error, check the token expiration time and refresh proactively before it expires.

Example: Robust Error Handling

async function callUniAuthAPI(url, options) {
  const response = await fetch(url, options);

  if (response.ok) {
    return await response.json();
  }

  const body = await response.json().catch(() => ({}));

  switch (response.status) {
    case 401:
      // Token expired — attempt refresh
      if (body.error === "invalid_grant" || body.message?.includes("expired")) {
        const refreshed = await refreshAccessToken();
        if (refreshed) {
          return callUniAuthAPI(url, {
            ...options,
            headers: { ...options.headers, Authorization: `Bearer ${refreshed.access_token}` }
          });
        }
      }
      // Redirect to login
      window.location.href = "/login";
      break;

    case 429:
      // Rate limited — wait and retry
      const retryAfter = parseInt(response.headers.get("Retry-After") || "60", 10);
      await new Promise(resolve => setTimeout(resolve, retryAfter * 1000));
      return callUniAuthAPI(url, options);

    case 423:
      // Account locked (may be returned by admin APIs)
      throw new Error("Account locked. Please try again later.");

    default:
      throw new Error(body.message || body.error_description || "An unexpected error occurred");
  }
}