Troubleshooting
Troubleshooting
Work down from the status code. Every failure below has a machine-readable error code in the response body — branch on that, not on the message text.
First move: check what you actually are
Most puzzling failures are scope problems. Ask the API:
curl https://api.falcata.io/api/v1/auth/whoami \
-H "Authorization: Bearer $FURNACE_TOKEN"
By status code
| Code | Meaning | Recovery |
|---|---|---|
401 | Token missing, expired, or revoked | Re-authenticate; the WWW-Authenticate header links the OAuth discovery documents |
403 | Identity known, action not allowed | Distinguish the error code: permission denial → request access; entitlement denial → plan limitation |
404 | Not found — or not visible to you | Some resources hide their existence from identities without access; verify the id and your scope before assuming deletion |
409 | Idempotency conflict | idempotency_in_progress: the original request is still running — wait and retry with the same key. idempotency_replay_unavailable: replay window passed — safe to decide anew |
429 | Rate limited (600/min, burst 100) | Honor Retry-After; watch RateLimit headers to stay ahead of it |
CLI
Stale credentials fail as 401 — furnace auth login again; the CLI re-reads its auth file per call, so no restart is needed. Talking to the wrong environment usually means FURNACE_API_URL or FURNACE_PROFILE is set from a previous task.
MCP
If tools/list works but tools/call fails, that's expected without credentials — listing is anonymous, calling is not. Auth failures on tools/call are the same 401/403 semantics as REST, with the same recoveries.
Still stuck, or the API behaves differently than these docs claim? Send feedback.