When something goes wrong, the API returns a consistent JSON envelope:

json

{
  "error": "Human-readable message",
  "code": "snake_case"
}

Here's every code you might hit.

Error reference

Code	HTTP	What happened	What to do
`unauthorized`	401	Missing, invalid, revoked, or expired API key	Check your `Authorization: Bearer fmk_…` header
`plan_required`	403	Org not on Team or Business	Upgrade plan or use dashboard instead
`scope_mismatch`	403	Project-scoped key can't access requested project	Pass the right project slug, or use an org-wide key
`rate_limited`	429	Over 120 requests per 60 seconds	Back off and retry
`not_found`	404	Session, override, log, or body doesn't exist	Check ids and query params
`project_required`	422	Org-wide key without `project`	Add `?project=your-slug`
`environment_required`	422	Multi-endpoint project without `environment`	Add `?environment=your-slug`
`invalid_override`	422	Bad override id or scenario-local override	Use published, non-scenario override ids
`invalid_mode`	422	DELETE `mode` isn't `reset` or `delete`	Use `?mode=reset` or `?mode=delete`
`invalid_side`	422	Body fetch `side` isn't `request` or `response`	Use `?side=request` or `?side=response`

Common patterns

401 on every call Key typo, wrong prefix, or revoked key. Create a fresh one in Settings → API keys.

403 plan_required Public API is a Team+ feature. Dashboard session control still works on lower plans.

422 environment_required Your project has multiple proxy endpoints. Add environment=staging (or whichever slug you need).

404 on GET session Session doesn't exist yet. Use PUT to create it first.

Production limit: 120 requests per 60 seconds per API key.

If you're polling logs, use reasonable intervals. Batch assertions where you can.