# Errors

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

```json
{ "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](https://www.closefinch.com/docs/quickstart/rest) or `ra sandbox create`.