# Errors

> For the complete documentation index, see [llms.txt](https://bordfeed.com/llms.txt).

Every error code the Bordfeed API returns, what it means and what to do next.

## Error format

Every error from the API has the same JSON shape. `error.code` is stable and
safe to branch on; `error.message` is written for people and can change.

```json
{
  "error": {
    "code": "not_found",
    "message": "Feed not found"
  },
  "docs_url": "https://bordfeed.com/docs/errors#not_found",
  "request_id": "req_91c6d7f9ce5341aaa0c4"
}
```

- `docs_url` links to the section for that code on this page.
- `request_id` identifies the request. Include it when you contact support.
- Some codes add fields inside `error`, listed with each code below.

## API errors

### `bad_request`

Status `400`. A value in the path, query or body could not be read, for example
a feed id that is not a UUID or a cursor that is not valid. Fix the request; a
retry with the same values fails the same way.

### `unauthorized`

Status `401`. The API key is missing, wrong, expired or revoked. Send the key
as `Authorization: Bearer bf_live_...` or in an `x-api-key` header. The error
includes `auth_md_url`, a link to [auth.md](https://bordfeed.com/auth.md), which explains how to
get a key. Create keys in the dashboard under **API Keys**.

### `payment_required`

Status `402`. Your plan's included jobs for the month are used up, so no full
jobs are returned. Lists, search and jobs you already received stay free. Wait
for the next billing period or change plan in the dashboard; see
[Pricing](https://bordfeed.com/pricing).

### `insufficient_credits`

Status `402`. On pay as you go, your credit balance cannot cover the unpaid
jobs in this response, so none are returned. The error includes:

| Field               | Meaning                                                                 |
| ------------------- | ----------------------------------------------------------------------- |
| `balance_jobs`      | How many full jobs your balance still covers.                           |
| `price_per_job_usd` | The price of one full job.                                              |
| `topup_url`         | A link that opens Stripe Checkout for this workspace for about an hour. |

Top up, then send the same request again. `GET /api/v1/billing/balance` returns
your balance at any time.

### `forbidden`

Status `403`. The key is valid but this action is not allowed, for example
creating a feed when the workspace has reached its feed limit. The message says
which limit or permission applies.

### `not_found`

Status `404`. Nothing with that id exists in your workspace, or the job is no
longer active. Ids from another workspace also return `not_found`.

### `conflict`

Status `409`. The change clashes with something that already exists, for
example a feed name another feed in the workspace already uses. Change the
value and send the request again.

### `validation_error`

Status `422`. The request was read, but a field has a value that is not
allowed: an unknown filter, a number out of range, an id that is not a UUID.
When there is more detail, `error.errors` lists each problem with the field it
belongs to.

### `rate_limit_exceeded`

Status `429`. Your workspace sent requests faster than its plan allows. Wait
the number of seconds in `error.retry_after` (also in the `Retry-After` header)
and try again. The `RateLimit-Limit`, `RateLimit-Remaining` and
`RateLimit-Reset` headers show where you stand. The limits per plan are in
[Rate limits](https://bordfeed.com/docs/mcp#rate-limits); API keys and MCP share them.

### `compile_limit_reached`

Status `429`. Creating or updating a feed from a plain-language `description`
uses one of your workspace's daily compiles, shared by the dashboard, the API
and MCP. The count resets at 00:00 UTC, and `error.retry_after` gives the
seconds until then. Sending `filters` instead of a `description` does not use a
compile.

### `server_error`

Status `500`. Something failed on Bordfeed's side. Retry after a short wait. If
it keeps failing, contact support with the `request_id`.

### `service_unavailable`

Status `503`. A service the request depends on is briefly unavailable. Wait the
seconds in `error.retry_after` (30, also in the `Retry-After` header) and send
the same request again.

## Agent sign-up errors

`POST /api/agent/register` and `POST /api/agent/verify` let an AI agent get an
API key with an emailed code. They use the same error shape and these codes;
[auth.md](https://bordfeed.com/auth.md) describes the whole flow.

### `invalid_request`

Status `400`. The request body is not valid JSON or is missing a required
field.

### `invalid_email`

Status `400`. That email address cannot be used to sign up.

### `invalid_agent_name`

Status `400`. `agent_name` must be 1 to 64 letters, digits, spaces or
`. _ ( ) -`, and must not be a URL or a domain.

### `invalid_code`

Status `400`. The code is wrong. `error.attempts_remaining` says how many tries
are left before the registration locks.

### `account_disabled`

Status `403`. This account is disabled.

### `two_factor_required`

Status `403`. The account uses two-factor authentication, so an emailed code
cannot issue a key. Sign in and create a key in the dashboard under
**API Keys**.

### `signup_disabled`

Status `403`. Public sign-up is turned off.

### `invalid_registration`

Status `404`. No registration matches that id. Register again.

### `workspace_not_found`

Status `404`. The `workspace` you sent is not one this account belongs to.

### `already_issued`

Status `409`. This registration already returned its API key, and a key is
shown only once. If it was lost, revoke it in the dashboard and register again.

### `workspace_required`

Status `409`. The account belongs to more than one workspace. Send `workspace`
as the organization id, slug or name. `error.workspaces` lists the choices.

### `code_expired`

Status `410`. The code has expired. Register again to get a new one.

### `locked`

Status `423`. Too many wrong codes. This registration is locked; register again
to get a new code.

### `email_send_failed`

Status `502`. The email with the code could not be sent. Register again to get
a new code.
