Back to error codes
ERROR 403
Forbidden
HTTP Error
The server understood the request but refuses to authorize it.
Root Cause
The user does not have the necessary permissions for the resource, even if authenticated.
How to Fix
Check your user scopes or roles. Ensure you are accessing a resource you have permission for.
Quick Summary
403 Forbidden means the caller is authenticated but not allowed to access this resource. Use 401 if no credentials were presented, 404 if the resource's existence should be hidden.
Key Takeaways
Key Takeaways
- 403 = identity is known, permission is denied
- Prefer 404 over 403 when revealing existence is itself a leak (e.g. private repos, admin URLs)
- Return JSON explaining which permission or scope is missing so clients can drive a clean UI
- Avoid distinct messages for 'user not in org' vs 'user lacks role' if either would leak info
Use Cases
When to use it
- Standard user calling an admin-only endpoint
- JWT missing the required scope (e.g. `users:write`)
- IP-based or geo-based access blocks
Watch out
Common Mistakes
- Returning 403 for unauthenticated requests, should be 401
- Returning 403 for non-existent resources, leaks that the resource exists; return 404 instead
- Hardcoding role names in the error message, they become part of your public API surface
FAQ
403 Forbidden, Frequently Asked
Can I return 403 from a CORS preflight?
Avoid it, browsers will block the actual request without surfacing the reason. Authorize the OPTIONS request unconditionally and apply the check on the real method.
Still having issues?
Check your network logs or use our developer tools to inspect headers, decode tokens, or validate your requests.