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.

{
  "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 shape instead: {"error": "invalid_grant", "error_description": "…"}.