> ## Documentation Index
> Fetch the complete documentation index at: /docs/llms.txt
> Use this file to discover all available pages before exploring further.

# API Errors: Status Codes and Error Format

> Error codes, response format, and troubleshooting guidance for the Buckle API. Learn what each HTTP status means and how to handle failures.

The Buckle API uses standard HTTP status codes to indicate the outcome of a request. Codes in the `2xx` range indicate success, `4xx` codes indicate a client error, and `5xx` codes indicate a server error.

This page covers the **management API** (`api.buckle.dev/v1`). Errors on an agent's proxied traffic (requests that ride the gateway to a provider) use flat, code-tagged bodies documented separately in [Gateway errors](/docs/api-reference/gateway-errors.md).

## Error response format

Error responses come in two shapes. Route-level validation errors return a flat `error` string:

```json theme={null}
{
  "error": "Label is required"
}
```

For validation errors, the message is the first issue reported by the validator.

Authentication failures and service errors use an envelope with a `message` and a `type`:

```json theme={null}
{
  "error": {
    "message": "Invalid API key or token.",
    "type": "authentication_error"
  }
}
```

Handle both: read `error` when it is a string, otherwise `error.message`.

The envelope's `type` is one of:

| Type | Used for |
| - | - |
| `authentication_error` | `401` and `403` from authentication, roles, plans, and quotas |
| `invalid_request_error` | `400`, `409`, `410`, and unknown routes |
| `not_found_error` | `404` |
| `validation_error` | `422` |
| `rate_limit_error` | `429` |
| `enterprise_license_required` | `403` from an Enterprise endpoint on a Community deployment (see [Editions](/docs/api-reference/editions.md)) |
| `api_error` | `500` |

Some `401`s carry an extra `code` (for example when the organization requires SSO and the session did not come through it).

## Error reference

| Status | Meaning | Common causes | What to do |
| - | - | - | - |
| `400` | Bad Request | Missing required field, invalid field value, body fails validation | Check the request body against the endpoint's schema. Ensure required fields are present and values match expected types and formats. |
| `401` | Unauthorized | Missing or invalid API key, expired session, an organization key on a workspace endpoint without `X-Workspace-Id` | Verify your `Authorization` header and, with an organization key, send `X-Workspace-Id`. Regenerate your key with `POST /user/api-key/regenerate` if needed. |
| `403` | Forbidden | Insufficient role, a Cloud plan or quota limit, an Enterprise feature on a Community deployment, not a member of the organization | Read the message. Plan and quota messages name the plan; license messages name the feature. |
| `404` | Not Found | Resource ID doesn't exist, wrong provider name, or the resource belongs to another workspace or organization | Confirm the resource ID or provider name exists. Use the corresponding list endpoint to check. |
| `409` | Conflict | Duplicate agent identifier; a turn already in flight on the conversation; a reorder list that no longer matches the rule set; an SSH key already registered | Choose a different identifier, use `POST …/messages` for follow-ups, or refresh and resend. (A `409` on an agent's *proxied* request is the [multiple-accounts protocol](/docs/api-reference/multi-account.md), not a management error.) |
| `410` | Gone | The endpoint was retired | The capability moved. The message says where; see the [retired endpoints](#retired-endpoints-410) inventory below. |
| `413` | Payload Too Large | An avatar over 1 MB or an attachment over 10 MB | Shrink the file. |
| `422` | Unprocessable | The body parsed but violates a validation law | Fix the field the message names (grant tool lists, rule pairing, schedule expressions, memory keys). |
| `429` | Too Many Requests | A throttled endpoint (SSO lookup, SSO connection test, SCIM) | Back off and retry. |
| `500` | Internal Server Error | Unexpected server failure | Retry after a brief delay. If the error persists, contact support. |

## Common error messages

### General

| Error message | Status | Cause |
| - | - | - |
| `"Invalid API key or token."` | 401 | Missing or invalid key, a revoked key, or a service-scoped key used on the management API |
| `"X-Workspace-Id (formerly X-Project-Id) header is required"` | 401 | An organization key (`oc_org_`) on a workspace endpoint without `X-Workspace-Id` |
| `"X-Workspace-Id (formerly X-Project-Id) header is required"` | 400 | An organization key reached a workspace-scoped sub-route of an account-level resource (for example `GET /user/api-key`) without `X-Workspace-Id`; a dashboard session resolves its workspace automatically |
| `"Not authenticated"` (flat shape) | 401 | A session-only endpoint (`POST /invitations/accept`, `POST /provisions/claim`) called with an API key or no session |
| `"Not a member of this organization"` | 403 | The key's or session's user is no longer an active member |
| `"Insufficient permissions"` | 403 | The endpoint requires the admin or owner role |
| `"… requires a Buckle Enterprise license."` | 403 | An Enterprise endpoint on a Community deployment (`type: enterprise_license_required`) |
| `"This feature requires the … plan."` | 403 | A plan-gated feature on Cloud |
| `"… limit reached (n/m on the … plan). Upgrade to add more."` | 403 | A quota on Cloud |
| `"Unrecognized request URL (METHOD: path). …"` | 404 | No such endpoint |

### Agents

| Error message | Status | Cause |
| - | - | - |
| Zod validation message for `name` (1-255 characters) | 400 | Empty or overly long `name` field |
| `"Identifier must be 1-50 characters, start with a letter or number, and contain only lowercase letters, numbers, and hyphens"` | 400 | Invalid identifier format |
| `"harness is only valid for hosted agents"` / `"instructions is only valid for hosted agents"` | 400 | Hosted-only fields on a `byo` agent |
| `"At least one field to update is required"` | 400 | `PATCH /agents/{agentId}` with an empty body |
| `"An agent with this identifier already exists"` | 409 | Duplicate `identifier` within the workspace |
| `"No runner is available to host this agent. Start a runner and try again."` | 422 | Creating a hosted agent with no runner online |
| `"Only hosted agents can hold schedules"` / `"… skills"` | 422 | A schedule or agent-tier skill on a `byo` agent |
| `"Agent not found"` | 404 | Agent ID doesn't exist in this workspace |

### Secrets

| Error message | Status | Cause |
| - | - | - |
| `"Secret value is required"` | 400 | Inline secret without a `value` |
| `"Select a 1Password field"` | 400 | `valueSource: onepassword` without `opRef` |
| `"Enter a hostname, not a URL (remove http:// or https://)"` | 400 | `hostPattern` includes a protocol prefix |
| `"Enter a hostname only, not a path (use the path pattern field for paths)"` | 400 | `hostPattern` includes a `/` path |
| `"Host pattern must not contain spaces"` | 400 | `hostPattern` contains whitespace |
| `"A host pattern must end in a literal domain …"` / `"A wildcard can't cover a public suffix …"` | 400 | A wildcard that would span unrelated owners |
| `"At least one field must be provided"` | 400 | PATCH request with an empty body |
| `"Secret not found"` | 404 | Secret ID doesn't exist |

### Grants

| Error message | Status | Cause |
| - | - | - |
| `"Custom access needs at least one allowed or approval tool. To block everything, detach instead."` | 422 | A custom grant with both lists empty |
| `"A tool can't be both always-allowed and require approval."` | 422 | The same tool id in `allow` and `ask` |
| `"Unknown tool id(s) for \"{provider}\": {ids}"` | 422 | Tool ids not in the provider's catalog; read `GET /apps/{provider}/permission-definition` |
| `"Per-tool permissions need a permission catalog; \"{provider}\" has none."` | 422 | A custom grant on an app without a tool catalog; use full access |
| `"Outside the access your organization allows for this connection: …"` | 422 | A `resources` scope wider than the organization's boundary |
| `"Resource-level access requires a Buckle Enterprise license."` | 403 | `resources` on a Community deployment |
| `"Agent not found."` / `"Connection not found."` / `"Secret not found."` | 404 | The id doesn't exist in this workspace's pool |

### Policy rules (organization)

| Error message | Status | Cause |
| - | - | - |
| `"rateLimit and rateLimitWindow must be provided together"` | 422 | One rate-limit field set without the other |
| `"rate-limit and approval modifiers require action = allow"` | 422 | `rateLimit` or `requireApproval` on a `block` rule |
| `"resource scoping (repositories/folders) requires a connection target"` | 422 | A session-policy `conditions` object without a connection target |
| `"At least one field must be provided"` | 422 | `PATCH /org/policy/rules/{ruleId}` with an empty body |
| `"Policy rule not found."` | 404 | Rule ID doesn't exist (published row ids regenerate every publish; match by `logicalId`) |
| `"Rule set changed. Refresh and try again."` | 409 | Reorder list didn't name every non-default rule exactly once |

### Conversations

| Error message | Status | Cause |
| - | - | - |
| `"This conversation already has a turn in progress"` | 409 | `POST …/turns` while the conversation is busy; use `POST …/messages` |
| `"This turn has already finished"` | 409 | Aborting a turn that reached a terminal state |
| `"Files are capped at 10MB."` | 413 | Attachment too large |
| `"The file is empty."` / `"Unreadable upload."` | 422 | Empty or malformed attachment body |

### Apps

| Error message | Status | Cause |
| - | - | - |
| `"Unknown provider: {provider}"` | 404 | Provider name not in the app registry |
| `"Provider \"{provider}\" is not available"` | 400 | Not an OAuth app (authorize) or unknown app (connect) |
| `"{App} is not configured. Missing required credentials."` | 400 | OAuth app without an OAuth client at the workspace, organization, or deployment level |
| `"Missing fields in request body"` | 400 | No `fields` object in connect request |
| `"{field} is required"` | 400 | A required credential field is empty |
| `"Organization-scoped connections are not supported on this server"` | 400 | `X-Organization-Id` or `_org` on a deployment without organization connect handlers |
| `"Connection not found"` | 404 | Connection ID doesn't exist or isn't owned by the caller |
| `"Label is required"` | 400 | Rename request without a non-empty `label` |
| `"Invalid request body"` | 400 | OAuth client configuration body missing the app's required fields |

### User

| Error message | Status | Cause |
| - | - | - |
| Zod validation message (for example `"Too small: expected string to have >=1 characters"`) | 400 | Empty or overly long `name` field |
| `"Only ed25519 public keys are supported — generate one with: ssh-keygen -t ed25519"` | 422 | Registering a non-ed25519 SSH key |
| `"This key is already registered on your account."` | 409 | Duplicate SSH key |
| `"SSH key limit reached (25). Delete a key you no longer use first."` | 409 | Too many SSH keys |

## Retired endpoints (410)

The move to [agent grants](/docs/guides/agent-access.md) retired the legacy rules model and the workspace-scope policy CRUD, and the hosted-agent redesign retired the default-agent concept. Retired paths answer `410 Gone` with a message that names the replacement. The pointer differs by scope, because the capability split: **workspace access** is written through grants, while **organization rules** keep the full policy console.

Workspace-scope tombstones end with:

> `Workspace access is granted per agent: PUT /v1/agents/:agentId/grants/connections/:connectionId and /v1/agents/:agentId/grants/secrets/:secretId.`

Organization-scope tombstones end with:

> `Use /v1/org/policy: one first-match rule set covering blocks, allows, rate limits, approvals and app permissions.`

| Retired path | What the message says | Where it went |
| - | - | - |
| `GET /v1/agents/default` | The default-agent concept is retired; list agents and pass one explicitly to `/v1/container-config` | `GET /v1/agents` + `?agent=` |
| `POST /v1/agents/{agentId}/set-default` | New default agents can no longer be set; pin a machine to an agent instead | `buckle config set agent` |
| `/v1/rules/*` | `/v1/rules was removed.` | Grants (workspace) |
| `/v1/rules/permissions/{provider}` | App permissions are policy rules with an app target; tool catalog at `/v1/apps/permission-definitions` | Grants + catalog |
| `/v1/rules/overlap/{provider}` | Overlap is computed by the organization Policy console | Org console |
| `/v1/org/rules/*` | `/v1/org/rules was removed.` | `/v1/org/policy/*` |
| `/v1/org/settings` | The allow/deny posture is the scope's Default Rule | `/v1/org/policy/default` |
| `PATCH /v1/agents/{agentId}/secret-mode` | Agents are always selective now; attach credentials with the grants endpoints | Grants |
| `/v1/agents/{agentId}/secrets` | Grant a secret to the agent instead | `PUT …/grants/secrets/{secretId}` |
| `/v1/agents/{agentId}/connections` | Grant a connection to the agent instead | `PUT …/grants/connections/{connectionId}` |
| `/v1/agents/granular-access` | Resource scoping rides the granting rule's conditions | Grant `resources` |
| `/v1/policy/rules`, `/v1/policy/rules/{ruleId}`, `PUT /v1/policy/rules/order` | Removed at workspace scope: workspace rules are compiled from agent credential grants, not authored directly | Grants |
| `/v1/policy/default`, `POST /v1/policy/publish`, `GET /v1/policy/last-publish` | Removed at workspace scope (same message) | Grants / org policy |
| `/v1/connections/{connectionId}/agents` | An agent reaches a connection through its grant; `GET …/effective-agents` reports who can, read-only | Grants + reflection |
| `/v1/org/agent-groups/*`, `/v1/org/agents/*`, `/v1/agents/{agentId}/groups` | Agent groups were removed: organize people with user groups (`/v1/org/groups`) | Groups (Enterprise) |

`GET /v1/policy/effective-app-permissions` is **not** retired. It is the surviving workspace-scope reflection.

The `/v1/partner/*` and `/v1/org/partner/*` endpoints and the `POST /v1/migrate/export` endpoint of earlier releases no longer exist and answer `404`.

## Retry guidance

Most `4xx` errors are not retryable. They indicate a problem with the request that must be fixed before retrying.

| Status | Retryable? | Notes |
| - | - | - |
| `400` | No | Fix the request body |
| `401` | No | Fix authentication |
| `403` | No | Check permissions, plan, or license |
| `404` | No | Fix the resource ID or path |
| `409` | No | Refresh state or change the identifier (proxied 409s: [add the connection header](/docs/api-reference/multi-account.md)) |
| `410` | Never | Permanent; move to the replacement endpoint |
| `413` | No | Shrink the upload |
| `422` | No | Fix the field the message names |
| `429` | Yes | Back off, then retry |
| `500` | Yes | Retry with exponential backoff |

For `500` errors, retry with exponential backoff:

```bash theme={null}
# Simple retry with backoff
for i in 1 2 3; do
  response=$(curl -s -w "\n%{http_code}" \
    -H "Authorization: Bearer $BUCKLE_API_KEY" \
    https://api.buckle.dev/v1/agents)

  status=$(echo "$response" | tail -1)
  [ "$status" -ne 500 ] && break

  sleep $((2 ** i))
done
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.