fetchbean API errors: types, codes, and error handling

Whenever a fetchbean API call fails, the response body contains a unified error envelope with a matching HTTP status code. Every error — whether it originates from a bad request, an auth failure, or an upstream provider — uses the same structure, so you can write one error-handling path that works across all providers and endpoints.

Error envelope

Every non-2xx response from fetchbean looks like this:

{
  "error": {
    "type": "auth",
    "code": "invalid_key",
    "message": "invalid API key",
    "retryable": false,
    "billable": false
  }
}

Each field serves a distinct purpose:

Field	Type	Description
`type`	string	The error category. Use this to drive top-level branching in your error handler.
`code`	string	A stable, specific code within the category. Use this when you need fine-grained handling.
`message`	string	A human-readable description of what went wrong. Safe to surface to logs or users.
`retryable`	boolean	Whether sending the same request again might succeed. Use this to decide whether to back off and retry.
`billable`	boolean	Whether the call consumed any credits. Provider failures and timeouts are always `false`.

Error types

Type	HTTP	Meaning
`validation`	400	The request body is missing or malformed. Fix the request before retrying.
`auth`	401	Missing, invalid, or unauthorized credential. Check your `X-API-Key` header.
`insufficient_credits`	402	Your balance can’t cover the call’s reserved maximum. Top up and retry.
`rate_limited`	429	Too many requests, or a same-key request is still in flight. Back off and retry.
`provider`	502	The upstream provider failed. Billed at zero.
`timeout`	504	The provider didn’t respond in time. Billed at zero.
`normalization`	502	A curated tool couldn’t map the provider response to a stable shape. Billable — the provider call itself succeeded.

Codes worth handling

A few code values inside those types come up often enough to branch on directly:

Code	Type	What to do
`credential_required`	`auth`	The tool runs on your own account and isn’t connected yet. Connect the provider in the dashboard — see Connections. Billed at zero.
`beta_unavailable`	`auth`	The operation is in beta and not enabled for your org. Email `hi@fetchbean.com` to request access.
`request_in_progress`	`rate_limited`	A request with the same `Idempotency-Key` is still running. Wait and retry the same key.
`idempotency_replay_unavailable`	`validation`	That key was already used for a request that never completed. Use a new key.
`spend_cap_exceeded`	`rate_limited`	The call’s upfront hold would put committed usage above your org’s monthly spend cap. Retry after the cap resets or is raised.

Handling errors

Branch on type for the main decision logic, and use code when you need to handle a specific failure scenario. Use the retryable flag to determine whether a retry is appropriate:

const res = await fetch('https://api.fetchbean.com/v1/search', { /* ... */ });
if (!res.ok) {
  const { error } = await res.json();
  if (error.retryable) {
    // back off and retry
  } else if (error.type === 'insufficient_credits') {
    // prompt a top-up
  } else {
    // surface error.message
  }
}

You are never charged for provider or timeout errors. Their billable field is false. normalization is the exception: the provider call succeeded and cost real money, but fetchbean could not map its result to the curated shape. Fall back to POST /v1/run to get the registered operation’s provider-specific result.

Read billable rather than inferring from the status code. Admission checks the call’s upfront hold against the available balance and monthly cap. A metered call’s final charge can exceed that hold, the remaining balance, or the cap after admission.

Get Started

Core Concepts

Guides

Reference

fetchbean API errors: types, codes, and error handling

Error envelope

Error types

Codes worth handling

Handling errors

​Error envelope

​Error types

​Codes worth handling

​Handling errors

Error envelope

Error types

Codes worth handling

Handling errors