Errors
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.
{
"error": {
"code": "not_found",
"message": "Feed not found"
},
"docs_url": "https://bordfeed.com/docs/errors#not_found",
"request_id": "req_91c6d7f9ce5341aaa0c4"
}docs_urllinks to the section for that code on this page.request_ididentifies 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, 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.
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; 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 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.