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

# Errors and limits

> Status codes, the error body, item-level outcomes, and rate limiting.

Errors return a machine-readable code in a small body:

```json theme={null}
{ "error": "invalid_request" }
```

## Batch errors — `POST /v1/signals`

| Status | `error` | When |
| - | - | - |
| `401` | `invalid api key` | Missing, malformed, revoked or expired key. |
| `402` | `out_of_credits` | The batch would exceed the account's balance. |
| `422` | `invalid_request` | Malformed body, unknown or ungoverned signal, empty `inputs`, or over the size limit. |
| `429` | `rate_limited` | Your request rate, or the items you already hold queued, is over the account's limit. |

An unknown key anywhere in the request body is a **malformed request, not ignored** (`422`).

## Poll errors — `GET /v1/signals/{request_id}`

| Status | `error` | When |
| - | - | - |
| `401` | `invalid api key` | Missing, malformed, revoked or expired key. |
| `404` | — | No batch with that `request_id` exists for the account. |

## Item-level outcomes

An item is never a transport error. Within a `200`/`202` batch an item can be `rejected`
(`no_runnable_signal`, `invalid_phone`, …), `error`, or `unresolved`. A per-signal vendor
outage degrades that signal to `null` — it never fails the whole batch. See
[item outcomes](https://docs.truthfactor.ai/essentials/verdicts.md#item-outcomes).

## 429 vs 422

> [!NOTE]
>
> Every `429` carries a `Retry-After` header — whole seconds, always at least 1 — so a refusal
> always tells you when to come back. A `422` never does. That is the distinction worth coding
> against: a `429` is "not yet", a `422` is "not like this".

A batch larger than the account's own ceilings is a `422` on `inputs` rather than a `429`,
because no amount of waiting would make it fit.

## Rate limits and batch size

> [!WARNING]
>
> Published numbers are **to be finalized**. The `429 rate_limited` response, its `Retry-After`
> header, and the `x-limits` fields in the OpenAPI spec are documented, but the maximum batch
> size and per-account rate limit are not yet set.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.