# Check errors

Every Check error has the same shape over REST and MCP: a stable code, a message a person can act on, and whether retrying can help.

The REST API and the MCP tools return the same error object. Branch on `code`, not on the message. On MCP the object is the text of a tool result marked `isError`.

```
{
  "error": {
    "type": "conflict",
    "code": "idempotency_in_flight",
    "message": "The same call is still running. Retry after retryAfter seconds; it will not charge again.",
    "retryable": true,
    "retryAfter": 5,
    "docUrl": "https://www.hirebestie.com/docs/check/errors#idempotency_in_flight",
    "requestId": "req_3f9c2a7d1e4b8c6a0f5d2e1b"
  }
}
```

## Fields

- `type`: the family of error, for coarse handling.
- `code`: the stable identifier. New codes may be added; existing ones keep their meaning.
- `message`: what happened and what to do, written for a person. Never a provider's raw error.
- `param`: the request field the error is about, when there is one.
- `requiredScope`: on `permission_denied`, the scope the connection lacks.
- `retryable`: true when sending the identical call again can succeed. False means change something first.
- `retryAfter`: seconds to wait before retrying, when known.
- `nextAction`: the next step, when there is one (for example the approval page).
- `details`: structured context for the code, such as the quote breakdown on `budget_exceeded`.
- `docUrl`: the section of this page for the code.
- `requestId`: quote it to support. REST also returns it in the `x-request-id` header.

> Retrying a paid call is safe: a verify with an approval that already ran returns that run with `replayed: true` and does not charge again.

## Codes

### applicability_undetermined

- HTTP status: `400`
- Type: `invalid_request`
- Retryable: no

The requested check cannot be decided on this document.

### approval_required

- HTTP status: `403`
- Type: `approval`
- Retryable: no

A person must approve this exact quote at approvalUrl before it can run.

### budget_exceeded

- HTTP status: `402`
- Type: `payment`
- Retryable: no

The quote is above the connection's spending limit.

### capability_unavailable

- HTTP status: `501`
- Type: `unavailable`
- Retryable: no

This capability is not offered on this surface or account.

### check_not_terminal

- HTTP status: `409`
- Type: `conflict`
- Retryable: yes

The check is still running. Poll again.

### conflict

- HTTP status: `409`
- Type: `conflict`
- Retryable: no

The resource changed. Read it again before acting.

### cross_tenant_access

- HTTP status: `403`
- Type: `permission`
- Retryable: no

The resource belongs to another workspace.

### expired_upload_handle

- HTTP status: `400`
- Type: `invalid_request`
- Retryable: no

The upload handle expired. Prepare the document again.

### extraction_failed

- HTTP status: `400`
- Type: `invalid_request`
- Retryable: no

The document could not be read. Replace the source.

### forbidden

- HTTP status: `403`
- Type: `permission`
- Retryable: no

The credential is valid but may not do this. details.reason names why.

### idempotency_error

- HTTP status: `400`
- Type: `invalid_request`
- Retryable: no

The same idempotency key was reused with different parameters.

### idempotency_in_flight

- HTTP status: `409`
- Type: `conflict`
- Retryable: yes

The same call is still running. Retry after retryAfter seconds; it will not charge again.

### insufficient_credits

- HTTP status: `402`
- Type: `payment`
- Retryable: no

The payer has too few credits for this quote.

### internal_error

- HTTP status: `500`
- Type: `api_error`
- Retryable: no

Bestie could not complete this request. Retry it; if it fails again, contact support with the requestId.

### not_found

- HTTP status: `404`
- Type: `not_found`
- Retryable: no

No such resource for this caller.

### oversized_upload

- HTTP status: `413`
- Type: `invalid_request`
- Retryable: no

The file is larger than the upload limit.

### pack_denied

- HTTP status: `403`
- Type: `permission`
- Retryable: no

This principle pack is not allowed for the workspace.

### pack_not_admitted

- HTTP status: `403`
- Type: `permission`
- Retryable: no

This principle pack is not admitted for checks yet.

### permission_denied

- HTTP status: `403`
- Type: `permission`
- Retryable: no

The token lacks the scope this action needs. requiredScope names it; a person can widen the connection's access in Bestie.

### rate_limited

- HTTP status: `429`
- Type: `rate_limit`
- Retryable: yes

Too many requests. Retry after retryAfter seconds.

### receipt_pending

- HTTP status: `409`
- Type: `conflict`
- Retryable: yes

The receipt is not settled yet. Poll again.

### service_unavailable

- HTTP status: `503`
- Type: `unavailable`
- Retryable: yes

Bestie is temporarily unavailable. Retry shortly.

### unauthorized

- HTTP status: `401`
- Type: `authentication`
- Retryable: no

The request has no valid credential. Reconnect or sign in again.

### unsupported_upload

- HTTP status: `400`
- Type: `invalid_request`
- Retryable: no

This file type is not supported.

### upstream_unavailable

- HTTP status: `503`
- Type: `upstream_unavailable`
- Retryable: yes

A service Bestie depends on is unavailable. Retry shortly; nothing was charged.

### validation_error

- HTTP status: `400`
- Type: `invalid_request`
- Retryable: no

The request is invalid. param names the field.
