# Errors

> The error object every failure returns, and the error codes each HTTP status carries.

Source: https://docs.fous.com/api-reference/errors
Index: https://docs.fous.com/llms.txt

A failure answers an HTTP error status with the object below. Branch on `error.code`; the [errors guide](https://docs.fous.com/guides/errors.md) says what each code means and what to do about it.

## The Error object

Every field sits under `error`.

- `error.code` (string, required): Stable code to branch on. The table below lists every code by status.
- `error.message` (string, required): What happened, in one or two plain sentences.
- `error.next_step` (string): What to do now, in one sentence.
- `error.doc_url` (string): This code’s entry in the errors guide (a policy refusal: the policy).
- `error.request_id` (string): The X-Request-Id of this request: quote it to support.
- `error.reason` (string): A finer cause when one helps: site_rate_limited, spend_limit, not_owned, stopped, body_too_large, sign_in_busy, step_expired, or (request_refused) the request check’s verdict: unclear, unsupported, explicit, harmful, platform_probe, refused.
- `error.retryable` (boolean): On a failed run: whether trying again can help (a block, a slow or failing site).
- `error.may_have_run` (boolean): A method with side effects failed after its request reached the site: check the site before running it again.
- `error.retry_after` (integer): Seconds to wait before trying again: the plan’s (rate_limited, with Retry-After), Fous’s (service_unavailable) or the site’s, when it said.
- `error.param` (string): The parameter at fault: input.<name> for an input, method for a method.
- `error.errors` (array of object): invalid_input: every input that does not fit, all at once. A required input that a misspelled name was meant for is listed as missing too; the message counts the two once.
  - `field` (string, required)
  - `problem` (string, required): One of `unknown`, `missing`, `type`, `enum`, `range`, `invalid`.
  - `message` (string, required)
  - `did_you_mean` (string): unknown: the input it most likely meant.
  - `expected` (string): type: the type it takes.
  - `allowed` (array of JSON value): enum: the values it takes.
- `error.method` (string): invalid_input: the method whose inputs these are.
- `error.input_schema` (object): invalid_input: the method’s own input_schema, exactly as stored.
- `error.example` (JSON value): invalid_input: a call that fits ({method, input}), from the method’s saved example (a write method’s is built from its schema). request_refused (unclear) and not_buildable: a request phrased so it can be built.
- `error.did_you_mean` (string): not_found: the method slug it most likely meant.
- `error.suggestions` (array of object): not_found: methods close to the name ({id, slug, name, summary}).
- `error.alternatives` (array of object): method_repairing: methods that do the same.
- `error.version` (integer): method_repairing: the version under repair.
- `error.latest_version` (integer): method_repairing: the method’s newest version; not_found for a version: the newest one there is.
- `error.repair` (object): method_repairing: when the version is expected back.
  - `expected_at` (string)
  - `back_in_minutes` (integer)
- `error.connect` (object): connection_required: the platform and connection type to connect, and connection_id when your organization already has a connection for the site.
  - `platform` (string)
  - `type` (string): One of `session`, `api_key`.
  - `connection_id` (string)
  - `status` (string): The status of your connection, when you have one. One of `pending`, `active`, `needs_attention`.
- `error.connect_url` (string): connection_required: the Fous Studio page where a person connects the account (your connection for the site, or a new one). A login also signs in with POST /v1/connections/{id}/sign-in.
- `error.attestation` (object): invalid_request without attest: true: the notice the person confirms before an account is connected or signed in.
- `error.billing_url` (string): insufficient_credits: where to add credits.
- `error.available_credits` (number): insufficient_credits: the credits the organization has.
- `error.required_credits` (integer): insufficient_credits: what the run, query or build costs.
- `error.private` (boolean): insufficient_credits on a build: a private method, which always costs credits.
- `error.free_builds` (object): insufficient_credits on a build: the month’s free builds.
  - `used` (integer)
  - `allowance` (integer)
  - `resets_at` (string)
- `error.spend_limit` (object): insufficient_credits with reason spend_limit: the monthly limit, what was spent, in credits, and when it resets.
  - `limit` (number)
  - `spent` (number)
  - `resets_at` (string)
- `error.limit` (object): rate_limited: the plan limit met, and its value when the plan sets one.
  - `kind` (string): One of `requests_per_minute`, `concurrent_runs`, `searches_per_minute`.
  - `value` (integer)
- `error.run_id` (string): The failed run (failures are free).
- `error.steps` (array of object): A failed query: the method calls it made and how each ended.

```json
{
  "error": {
    "code": "invalid_input",
    "message": "2 inputs don't fit date.nager.at/list_public_holidays: \"contry\" is not one of its inputs (did you mean \"country\"?), and \"year\" must be an integer from 1 to 9999.",
    "next_step": "Send the inputs below and run it again. Nothing was charged.",
    "param": "input.contry",
    "errors": [
      {
        "field": "contry",
        "problem": "unknown",
        "message": "Not an input of this method. Did you mean \"country\"?",
        "did_you_mean": "country"
      },
      {
        "field": "year",
        "problem": "type",
        "message": "Must be an integer from 1 to 9999; got \"next\".",
        "expected": "integer"
      },
      {
        "field": "country",
        "problem": "missing",
        "message": "Required."
      }
    ],
    "method": "date.nager.at/list_public_holidays",
    "input_schema": {
      "type": "object",
      "required": [
        "country"
      ],
      "properties": {
        "year": {
          "type": "integer",
          "minimum": 1,
          "maximum": 9999,
          "description": "Calendar year, for example 2026. Defaults to the current year."
        },
        "country": {
          "type": "string",
          "description": "Country name or two-letter country code, for example Germany or DE."
        }
      }
    },
    "example": {
      "method": "date.nager.at/list_public_holidays",
      "input": {
        "country": "Germany",
        "year": 2026
      }
    },
    "doc_url": "https://docs.fous.com/guides/errors#invalid_input",
    "request_id": "req_mh7c2k9xQ1v3Zt8LbN0pRwY4"
  }
}
```

## Codes by status

| Status | Codes |
| --- | --- |
| 400 | [`invalid_request`](https://docs.fous.com/guides/errors.md#error-codes) |
| 401 | [`unauthorized`](https://docs.fous.com/guides/errors.md#error-codes) |
| 402 | [`insufficient_credits`](https://docs.fous.com/guides/errors.md#error-codes) |
| 403 | [`forbidden`](https://docs.fous.com/guides/errors.md#error-codes), [`insufficient_scope`](https://docs.fous.com/guides/errors.md#error-codes), [`connection_required`](https://docs.fous.com/guides/errors.md#error-codes) |
| 404 | [`not_found`](https://docs.fous.com/guides/errors.md#error-codes) |
| 408 | [`request_timeout`](https://docs.fous.com/guides/errors.md#error-codes) |
| 409 | [`conflict`](https://docs.fous.com/guides/errors.md#error-codes) |
| 422 | [`invalid_input`](https://docs.fous.com/guides/errors.md#error-codes), [`request_refused`](https://docs.fous.com/guides/errors.md#error-codes), [`not_buildable`](https://docs.fous.com/guides/errors.md#error-codes) |
| 429 | [`rate_limited`](https://docs.fous.com/guides/errors.md#error-codes) |
| 500 | [`server_error`](https://docs.fous.com/guides/errors.md#error-codes) |
| 503 | [`upstream_error`](https://docs.fous.com/guides/errors.md#error-codes), [`upstream_blocked`](https://docs.fous.com/guides/errors.md#error-codes), [`upstream_timeout`](https://docs.fous.com/guides/errors.md#error-codes), [`method_unavailable`](https://docs.fous.com/guides/errors.md#error-codes), [`method_repairing`](https://docs.fous.com/guides/errors.md#error-codes), [`service_unavailable`](https://docs.fous.com/guides/errors.md#error-codes) |