authentication_error

HTTP status: 401
Category: API authentication

What this error means

The Wocha API could not authenticate your request. The caller identity — management API key, OAuth access token, or bearer token — was missing, invalid, expired, or rejected by the auth subsystem.

This is a category-level error. Specific codes include unauthorized, invalid_key, expired_key, key_revoked, token_inactive, auth_failed, and introspection_failed.

Common causes

• Missing or malformed Authorization: Bearer … header
• Management API key does not match the configured tenant (WOCHA_TENANT)
• API key was revoked or has passed its expires_at date
• OAuth access token expired or was revoked
• Transient failure in the authentication subsystem (auth_failed)

How to fix it

1. Verify WOCHA_API_KEY and WOCHA_TENANT in your environment match a valid key in Console → Settings → API keys.
2. Confirm the key has not expired or been revoked; rotate if needed.
3. For OAuth tokens, refresh the access token or re-run the authorisation flow.
4. Do not retry indefinitely — fix credentials first. Only auth_failed may warrant a single retry.
5. Include request_id from the error when contacting support.

Example

import { WochaAuthenticationError } from "@wocha/sdk";
 
try {
  await wocha.users.list();
} catch (err) {
  if (err instanceof WochaAuthenticationError) {
    switch (err.errorCode) {
      case "invalid_key":
      case "expired_key":
      case "key_revoked":
        console.error("Rotate your management API key:", err.docsUrl);
        break;
      case "token_inactive":
        await refreshOAuthToken();
        break;
      default:
        console.error(err.errorCode, err.requestId, err.docsUrl);
    }
  }
}

See also

• invalid_key · expired_key · auth_failed
• API keys guide