Errors

Every error from the REST API and the MCP server says what went wrong, what to do, and links here:

{ "error": { "code": "unauthorized", "message": "…", "fix": "…", "docs": "https://www.closefinch.com/docs/errors#unauthorized" } }

Over MCP, a JSON-RPC error carries the same fix and docs in error.data, and a tool's error result in its content. Rate limits are in X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset on every response.

bad_request

HTTP 400: The request didn't validate. Fix what the message (and details.issues, when present) names, then send it again.

unauthorized

HTTP 401: No credential, or a bad one. Send Authorization: Bearer <key>. Get a key in Settings → API keys, or create a sandbox with its own key: POST /v1/sandbox (or ra sandbox create).

forbidden

HTTP 403: Not allowed with this credential. Use a key with the scope the message names (Settings → API keys), or do this in the web app if it's web-only.

not_found

HTTP 404: No such thing. Check the id or the path. List the resource to find the id, or see /v1/openapi.json for the routes.

conflict

HTTP 409: It changed, or it can't happen in this state. Read it again and retry with its current version or state.

moved

HTTP 301: Merged into another record. Read the record at the Location header (details.merged_into) instead.

gone

HTTP 410: No longer available. It was removed or expired; don't retry.

rate_limited

HTTP 429: Too many requests. Wait the number of seconds in Retry-After, then retry. X-RateLimit-Remaining shows what's left.

policy_blocked

HTTP 422: The organization's policy refused it. Don't retry: tell a person which rule the message names (kill switch, consent, do-not-contact, budgets).

unavailable

HTTP 503: Temporarily unavailable. Retry after a short wait (the Retry-After header, when present).

internal

HTTP 500: Something failed on our side. Retry once. If it fails again, report the request id (the x-request-id header).

No key yet? Create a sandbox with its own limited key: quickstart or ra sandbox create.