# Errors

Every error from the REST API has the same shape. MCP tools return the same `code` and `fix` as the text of a tool error.

```json
{
  "type": "ErrorResponse",
  "error": {
    "id": "a3f9c2e1/xYz-000123",
    "status": 402,
    "code": "INSUFFICIENT_CREDITS",
    "detail": "the account has no credit left",
    "meta": {
      "fix": "add credit at https://ravenoutreach.com/app/credits",
      "docs_url": "https://ravenoutreach.com/docs/errors#INSUFFICIENT_CREDITS"
    }
  },
  "time": 1793256000
}
```

`meta.fix` says what to do next, written for both people and agents. Quote `error.id` when you contact support.

## Codes

### API_KEY_INVALID
**401.** The key or token is missing, wrong, expired or revoked. An OAuth token used at a different resource also gets this. Get a new key from the dashboard or `raven login`. An MCP client signs in again.

### UNAUTHORIZED
**401.** A dashboard request without a valid session. Sign in again.

### FORBIDDEN
**403.** The account is suspended, or a browser request lacks its CSRF token.

### SCOPE_INSUFFICIENT
**403.** The key or connection only has the `read` scope, and the call changes something. Use a key with `write`, or reconnect the app and allow write access.

### INSUFFICIENT_CREDITS
**402.** The account has no credit for this. Add credit at the `top_up_url` from `GET /v1/account`. Teams paused for credit resume by themselves.

### USAGE_LIMIT_REACHED
**402.** The account reached the monthly usage limit it set. Raise it in the dashboard, or wait for next month.

### NOT_FOUND
**404.** No such team, campaign or lead in this account.

### TEAM_STATE
**409.** The team can't do this in its current status. Examples: approving while it's still planning, or messaging an archived team. Check `GET /v1/teams/{id}`.

### PLAN_VERSION_STALE
**409.** A newer plan replaced the version you tried to approve. Show the new one to the user and approve that version.

### IDEMPOTENCY_IN_PROGRESS
**409.** A request with this `Idempotency-Key` is still running. Retry in a second to get its response.

### IDEMPOTENCY_KEY_REUSED
**422.** This `Idempotency-Key` was already used for a different request. Use a new key for each new request.

### VALIDATION_FAILED
**422.** The request is malformed. `detail` names the field.

### API_VERSION_INVALID
**400.** `Api-Version` isn't a date like `2026-11-01`.

### RATE_LIMITED
**429.** More than 20 requests a second. Wait `Retry-After` seconds, then retry with exponential backoff.

### INTERNAL_ERROR
**500.** Something failed on Raven's side. Retry shortly. If it persists, contact support with the error `id`.

## OAuth errors

The OAuth endpoints (`/oauth/*`) answer in the standard [RFC 6749](https://www.rfc-editor.org/rfc/rfc6749#section-5.2) shape instead: `{"error": "invalid_grant", "error_description": "…"}`.