Errors & Troubleshooting

6 min read·Updated May 7, 2026

A reference for every error Authaz returns. Use it like a debugger: search the page (⌘F / Ctrl+F) for the exact code or message your app is seeing, find the cause, apply the fix.

If your specific error isn't here, the API reference has the canonical response shape and HTTP status semantics.

These are returned by the OAuth endpoints (/oauth2/authorize, /oauth2/token, /oauth2/userinfo).

Code	Status	Most likely cause	Fix
`invalid_request`	400	The `redirect_uri` your code sends doesn't match what's registered in Settings → Redirect URIs. The #1 OAuth onboarding bug.	Compare exactly: trailing slash, port, vs , scheme. Add every dev/staging/prod URL.

Previous: API Reference
Next: How Authaz is Built

http

https

Status	`code` examples	Most likely cause	Fix
`401`	`unauthenticated`, `invalid_api_key`, `expired_token`	Missing, wrong, or expired credentials.	Verify `X-API-Key` (Management API key) or `Authorization: Bearer` (user JWT) is set and current.
`403`	`forbidden`, `insufficient_permissions`	Credentials valid, but the API key lacks the permission for this endpoint.	Grant the permission to the key in Dashboard → API Keys, or use a key that already has it.
`403`	`tenant_mismatch`	The credential is scoped to a different tenant than the resource.	Either use a credential scoped to the right tenant, or switch to a global Management API key.
`404`	`not_found`	Resource doesn't exist, OR exists but is in a tenant your credential can't see.	If you're sure it exists, check the credential's tenant scope — `404` is intentionally indistinguishable from `403` to prevent enumeration.
`409`	`conflict`, `email_already_exists`	Duplicate resource. Most common: creating a user/invitation with an email already in use.	Search first (`GET /users?search=email@…`) and decide whether to update or skip.
`422`	`validation_error`	Required field missing, format wrong, or value out of range. `field` names the offending input.	Check the field's schema in the API reference.
`429`	`rate_limited`	Too many requests. Returns `Retry-After` (seconds).	Back off and retry. SDKs do this automatically with the standard resilience handler.
`500`+	`internal_error`, `service_unavailable`	Server-side problem.	Safe to retry idempotent calls with exponential backoff. Persistent 5xx — contact support.

Code / symptom	Most likely cause	Fix
`no_tenant` (403)	The user signed in but didn't pick a tenant — the access token has no `tenant_id` claim.	Send them back through `/api/auth/login` to re-pick. Tenant binding happens at sign-in, not at runtime.
`tenant_mismatch` (403)	An authorization check ran without a `tenant_id`, or with the wrong one.	Always pass `tenant_id` from the access token to every `POST /api/v1/authorization/check`. Never read it from a header, query, or body.
Cross-tenant data leak	Your code keyed a session cache by `userId` alone. The same user can have different roles in different tenants.	Key session caches by `(userId, tenantId)`.

Symptom	Surface	Fix
`useAuthaz must be used within AuthazProvider`	React	`<AuthazProvider>` doesn't wrap the component using the hook. Move it higher in the tree.
`useAuthaz()` stuck on `isLoading: true`	React / Next.js	`basePath` prop on `AuthazProvider` doesn't match where the backend mounted the auth handler. Default is `/api/auth`.
`/api/auth/me` returns 401 immediately after login	Next.js / Hono	The OAuth callback page (`/auth/callback`) didn't re-POST the code into the handler. See the callback page in the Next.js quickstart.
Logged in, but a hard refresh signs the user out	React SPA	Session cookie isn't reaching the backend — same-site or cross-origin issue. In dev, use the Vite proxy. In prod, host frontend and backend under the same registrable domain.
`process.env.X` is `undefined` on Cloudflare Workers / Bun	Hono	Those runtimes don't auto-populate `process.env`. Pass env via `wrangler.toml` (Workers) or `bun --env-file=.env`.

Symptom	Fix
Every call returns `AuthazError.Unauthorized` (401)	API key wrong, missing, or you used the OAuth Client Secret. Management API needs `mgmt_01h…` from Settings → API Keys → Management.
`AuthazError.Network` on every call	Wrong `BaseAddress`, no internet, or DNS / firewall. Confirm `https://your-app.authaz.io` is reachable.
`result.Value` is `null` after `IsSuccess == true`	The endpoint returns no body (e.g. delete). `Value` is only populated on endpoints that return data.
`AuthazError.NotFound` for an ID you just created	Wrong tenant or organization scope. The ID must belong to the same scope as the API key.
DI throws `Unable to resolve service for IAuthazClient`	`AddAuthazSdk` not called, or called after `var app = builder.Build();`. Register before `Build()`.

Symptom	Cause	Fix
TLS / cert error on `your-app.authaz.io`	Custom domain isn't verified yet, or DNS hasn't propagated.	Check Settings → Custom Domains. New domains take up to ~24h to issue a certificate.
`CORS` errors on `/api/auth/me` from a SPA	Frontend and backend on different origins, no proxy or CORS config.	In dev, prefer same-origin via Vite/Next proxy. In prod, host both under the same registrable domain.
Behind a load balancer, cookies aren't `Secure`	The app doesn't see HTTPS because the LB terminates it.	Forward `x-forwarded-proto: https` so the SDK detects HTTPS.
`/.well-known/jwks.json` returns 404	Wrong host. The JWKS lives at the application's per-app subdomain.	Use `https://your-app.authaz.io/.well-known/jwks.json` — replace `your-app` with your application's slug.

Errors & Troubleshooting

Management API errors#

Multi-tenant errors#

SDK errors (TypeScript / JavaScript)#

SDK errors (.NET — `Authaz.Sdk`)#

Network and infrastructure#

When to contact support#

Sign-in flow errors (OAuth / OIDC)#