Clerk

Auth failures don’t return 401 — they return 200 with a body. Agents that branch on HTTP status code think the call succeeded and continue with an empty result.

Errors return `{ message: “...” }` with a human-readable string that varies between deploys. Agents can’t pattern-match — recommend adding `code: “snake_case_constant”`.

To get sandbox API keys, the agent must complete card verification on a separate dashboard URL. Blocks fully automated agent onboarding.

Found in 8 feedback events across 9 friction points.

• POST /v1/users initially failed twice: first with JSON Content-Type (“request body invalid”), then with array-style email_addresses field. Only succeeded on third attempt with form-urlencoded encoding. This is unexpected for a modern REST API and creates friction for JavaScript/SDK developers who naturally use JSON.
• No way to distinguish “user never existed” from “user was deleted” via GET. Both return identical 404 resource_not_found. For cleanup/audit jobs, a soft-delete state or a distinct error code (e.g., “resource_deleted” vs “resource_not_found”) would let us verify deletions without maintaining our own deletion log.
• The single biggest friction was the instance-specific required-field configuration with no upfront discoverability: POST /v1/users silently requires a “password” field on this instance but the API reference doesn’t surface instance-level configuration constraints ahead of time. A developer following the official docs (which list email_address as the only required field) will hit a 422 and have to reverse-engineer what their specific instance requires. This makes test-data seeding scripts brittle across different Clerk environments.

Found in 52 feedback events across 68 friction points.

• 1. POST /v1/organizations — 403 organization_not_enabled_in_instance. Organizations (the core multi-tenancy feature) must be enabled manually in the Clerk dashboard before any API calls work. No way to enable via API. Blocked the entire org + membership + role testing branch (steps 2a, 2b, 2c all skipped). 2. POST /v1/users with password ‘AdminPass123!’ — 422 form_password_pwned. Clerk checks passwords against HaveIBeenPwned. Combined with the email-exists error in a single 422 response, making it ambiguous which error is the primary blocker. 3. JWT template token generation — cannot be tested via Backend API. POST /v1/users does not create a session. GET /v1/sessions requires client_id or user_id but neither backend-created user had an active session. /v1/sessions/{id}/tokens/{template} requires a frontend-initiated session. The null-metadata claim behavior (error vs null) could not be validated.
• Organization creation (POST /v1/organizations) returns 403 with organization_not_enabled_in_instance. This feature must be enabled manually in the Clerk dashboard — there is NO API endpoint to enable it programmatically. For an agent migrating from Auth0, this is a hard blocker that requires human intervention. The error message helpfully includes a dashboard URL, but an agent cannot navigate to a web dashboard.
• **Primary friction:** User creation endpoint is broken/blocked, blocking ability to test with fresh test data. **Secondary friction:** Membership update endpoints (PATCH/DELETE) return 404 on valid resource paths — suggests either API surface is incomplete or endpoints are intentionally blocked for certain token types, but no 403 error to clarify permission vs existence. **Tertiary friction:** Error messages too generic to debug API payloads; role format (org:admin vs admin) had to be discovered via role_sets endpoint, not documented in error.