Skip to main content

Troubleshooting

Quick fixes for issues you might hit as a user of the API, SDK, CLI, or MCP.

"Can't reach the API" / connection errors​

  • Base URL — Use https://api.1claw.co for production. The dashboard at 1claw.co proxies /api/* to the same API, so from a browser you may use relative /api/v1/... when on the same origin.
  • CLI / SDK — Ensure your client is configured with the correct base URL. The SDK and CLI default to the production API when not set.
  • MCP — For hosted MCP, use https://mcp.1claw.co/mcp. For local stdio, ONECLAW_BASE_URL defaults to https://api.1claw.co; override only if you use a different API host.

The SDK returns null and nothing else​

Every SDK method returns an envelope, not the value:

interface OneclawResponse<T> {
  data: T | null;
  error: { type: string; message: string; detail?: string } | null;
  meta?: { status: number; requestId?: string };
}

data is null whenever error is set. So this reports nothing at all when the call is refused:

const { data: secret } = await client.secrets.get(vaultId, "api-keys/test");
console.log(secret); // null — and the reason was thrown away

Destructure error too. A 403 otherwise looks exactly like an empty secret:

const { data, error, meta } = await client.secrets.get(vaultId, "api-keys/test");
if (error) {
  console.error(meta?.status, error.type, error.message);
  console.error("request id:", meta?.requestId); // quote this to support
}

Once you can see the error, the usual causes are:

  • 403 Insufficient permissions — the agent's grant does not cover that path. GET /v1/vaults/{id}/access shows the paths actually granted; a "default read access" grant is often scoped to a prefix that excludes yours.
  • 404 — wrong path or wrong vault. client.secrets.list(vaultId) returns the keys (no plaintext) and settles it.
  • 403 mentioning the Intents API — the agent has intents_api_enabled and the secret's type is private_key or ssh_key. Only those two types are blocked from direct reads; other types are unaffected.

401 Unauthorized​

  • Missing or invalid token — Include Authorization: Bearer <token>. For agents, get a fresh JWT via POST /v1/auth/agent-token (tokens expire; the MCP server refreshes automatically when using agent ID + API key).
  • Revoked key — If you rotated an agent key or revoked a personal API key, use the new key or log in again.
  • Wrong credentials — For POST /v1/auth/token, use email and password (not username). Check for typos or wrong environment variable.

402 Payment Required​

  • Your request count has exceeded your tier’s monthly limit and the API is asking for payment (x402 or prepaid credits).
  • What to do: Upgrade your plan, add prepaid credits, or complete the x402 payment for this request. In the dashboard, go to Settings → Billing. See Billing & Usage.

403 Forbidden​

  • No permission for this resource — Your token is valid but you don’t have a policy that allows this action on this vault/path. Add or update a policy (dashboard: Vault → Policies), or use a vault you own or have been granted access to.
  • Resource limit exceeded — You’ve hit your subscription’s limit for vaults, secrets, or agents. The response body has type: "resource_limit_exceeded" and a message like "Vault limit reached (3/3 on free tier)". Upgrade your plan or delete unused resources. See Billing & Usage.
  • Intents API — You’re calling a transaction endpoint (e.g. submit or simulate) but your agent doesn’t have intents_api_enabled. Enable it in the dashboard (Agent → edit) or via the API.
  • IP denied — Your org has IP allow/block rules and your current IP is not allowed. Check Security → IP rules in the dashboard.

404 Not Found​

  • Vault or secret path — Check the vault ID and path. Paths are case-sensitive and must match exactly. Use list endpoints (GET /v1/vaults, GET /v1/vaults/:id/secrets) to confirm IDs and paths.
  • Agent ID — When calling agent or transaction endpoints, ensure the agent ID is correct and the agent belongs to your org.

410 Gone​

  • The secret has expired (expires_at passed), been soft-deleted, or exceeded max_access_count. Store a new version of the secret or use a different path.

429 Too Many Requests​

  • You’ve hit the global rate limit. Wait and retry; the response may include a Retry-After header. Share creation is also limited to 10 per minute per org.

MCP: "Access denied" or 403 on get_secret​

  • The agent must have a policy that grants read access to that vault and path. Create a policy in the dashboard (Vault → Policies) with the agent as principal and a path pattern that matches the secret (e.g. ** for all paths). See Give an agent access.

CLI: Device login not completing​

  • Approve the device code in the dashboard: go to the CLI verification page (linked from the CLI output) and sign in, then approve. Ensure you’re using the same account as the one that started the device flow.

For a full list of error codes and response shapes, see Error codes. For how the API processes requests (auth, rate limit, billing), see Request pipeline.

Need help?​

Last updated on