Skip to main content

API errors: 401, 403, 429

First: test your token​

This one-liner isolates almost every problem — run it with the exact token your tool is using:

curl -s -o /dev/null -w "%{http_code}\n" \
  -H "X-API-Key: writemars_pat_..." \
  https://api.writemars.com/api/workspaces/
  • 200 → the token is fine; the problem is in the client config.
  • 401 → the token is invalid, revoked, or expired (see below).

401 Unauthorized​

The token isn't being accepted. In order of likelihood:

  1. Revoked or expired — check Profile → API Tokens: the badge should say Active. If it's Revoked/Expired, create a new token.
  2. Truncated or padded — re-copy. The token starts with writemars_pat_ and has no spaces or line breaks.
  3. Wrong header — it must be X-API-Key: <token> or Authorization: Bearer <token>. (Api-Key:, X-Api-Token:, etc. are silently ignored and you'll get 401 for "no credentials".)
  4. Token managed elsewhere — note that /api/tokens/ itself never accepts a token (managing tokens requires being signed in to the app, by design).

403 Forbidden​

Your token authenticated fine but isn't allowed to do that. Two distinct causes:

  • "This API token is restricted to another workspace." — the token was created scoped to one workspace. Use it only there, or create an all-workspaces token (see Authentication).
  • "Access denied." — you aren't allowed to do that (e.g. editing a post outside your audience, or changing another member's connected account). This matches exactly what you could do in the app — see Permissions.
  • "You're not trusted to act as @handle." — you tried to create or run an auto-engagement rule as an account you can't act as: it must be your own, one you're trusted on, or (for admins) a company or team-engagement account.

Related: a 404 on a post a teammate can open usually isn't a bug — private posts return not-found to everyone outside their audience, admins included. And a 400 saying "This variant is awaiting channel approval." means the variant is in needs_approval and will publish once approved — see Publishing failures.

429 Too many requests​

Each token gets 120 requests/minute. The response includes Retry-After (seconds) — wait that long and retry. For batch jobs, spread requests or use multiple scoped tokens per integration. Agent sessions occasionally hit this during long multi-step tasks; they recover on their own. Details in Rate limits.