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

# Errors

> HTTP status codes returned by the Blitz API and how to handle them. A 422 lists every invalid or unknown request field with its path and the closest valid field or value, and uses no records.

# Errors

> Every error returns JSON with `success: false` and a readable `message`. A `422` also lists each invalid field.

<div style={{position:'absolute',width:'1px',height:'1px',padding:0,margin:'-1px',overflow:'hidden',clipPath:'inset(50%)',whiteSpace:'nowrap',border:0}}>
  > **Agents & LLMs**: a Markdown version of this page is available by appending `.md` to the URL, and the full documentation index is at [llms.txt](https://docs.blitz-api.ai/llms.txt).
</div>

## Status codes

| Code | Meaning | What to do |
| :- | :- | :- |
| `400` | Bad Request | The request body is not valid JSON. Send a JSON object with the header `Content-Type: application/json`. |
| `401` | Unauthorized | Missing or invalid `x-api-key` header. |
| `402` | Payment Required | Account limit reached. Upgrade your plan. |
| `404` | Not Found | API key does not exist. |
| `422` | Unprocessable Entity | A request field is unknown or has an invalid value. Fix the fields listed in `errors` and resend. See [below](#validation-errors-422). |
| `429` | Too Many Requests | Exceeded an endpoint's rate limit. Throttle client-side to your plan's `max_requests_per_seconds`. |
| `500` | Internal Server Error | Transient server error. Retry with exponential backoff. |
| `503` | Service Unavailable | The service is temporarily unavailable. Retry with exponential backoff. |

Only `429`, `500`, and `503` are worth retrying as-is. A `400` or `422` fails the same way until you change the request.

***

## Validation errors (422)

The API checks the request body before it runs the request, so a `422` never uses records. A body is rejected when it contains:

* **A field the endpoint does not define**, at any depth. A misspelled filter such as `company.industry.includes` returns a `422` instead of being ignored.
* **A value outside an accepted list**, such as an industry, job level, or employee range. These values are case-sensitive: copy them from [Field Normalization](/guide/reference/normalization).
* **A wrong type or an out-of-range value**, such as a string for `max_results` or more than 50 items in a filter list.

```json Invalid value theme={null}
{
  "success": false,
  "message": "Invalid request body. company.industry.include[0]: Invalid value \"Software\". Did you mean \"Computer Software\", \"Software Development\" or \"Embedded Software Products\"?",
  "errors": [
    {
      "field": "company.industry.include[0]",
      "message": "Invalid value \"Software\". Did you mean \"Computer Software\", \"Software Development\" or \"Embedded Software Products\"?"
    }
  ]
}
```

| Field | Type | Description |
| :- | :- | :- |
| `success` | `boolean` | Always `false`. |
| `message` | `string` | One-line summary of the first three errors, for logs. |
| `errors` | `array` | One item per problem, up to 20. |
| `errors[].field` | `string` | Path to the problem. Dots mark nesting and `[n]` marks an array item, e.g. `company.industry.include[0]`. |
| `errors[].message` | `string` | What is wrong. When the input is close to a valid field or value, it suggests the closest match. Otherwise a short list of allowed fields or values is given in full. |

For an unknown field, `field` is the object that contains it (`body` for a top-level field) and `message` names the rejected field:

```json Unknown field theme={null}
{
  "success": false,
  "message": "Invalid request body. company.industry: Unknown field \"includes\". Did you mean \"include\"?",
  "errors": [
    {
      "field": "company.industry",
      "message": "Unknown field \"includes\". Did you mean \"include\"?"
    }
  ]
}
```

<Tip>
  Read `errors[].field` to find what to fix, and treat `message` as text for humans: its wording can change.
</Tip>

<Note>
  Free-text filters such as `name`, `keywords`, `job_title`, `city`, and `country_code` are not checked against a list. A typo in one of them is not an error: the search runs and returns 0 results. See [Troubleshooting](/guide/reference/normalization#troubleshooting).
</Note>