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

# Errors

> Public HTTP statuses and error envelope. Details are field paths only.

Errors use the runtime envelope. Tera never echoes submitted payloads, names, emails, telephone numbers, evidence objects, HMAC values, or fingerprints.

```json theme={null}
{
  "error": {
    "code": "validation_error",
    "message": "Request failed schema validation.",
    "details": [
      { "path": "telephone", "message": "A UK-contactable telephone number is required" }
    ]
  }
}
```

Every response includes `X-Request-Id`. That header is the only correlation identifier. The JSON body does not include `request_id`.

## Statuses

| HTTP    | Code                          | When                                                                                     |
| ------- | ----------------------------- | ---------------------------------------------------------------------------------------- |
| **200** | —                             | Identical create replay, GET, or idempotent operation replay                             |
| **202** | —                             | New create persist, or promotion accepted for processing                                 |
| **400** | `bad_request`                 | Malformed JSON, invalid content type, or missing required query                          |
| **401** | `unauthorized`                | Missing or invalid credential                                                            |
| **403** | `forbidden`                   | Valid credential but insufficient scope or unauthorised level. No row is created.        |
| **404** | `not_found`                   | Unknown or cross-tenant `submission_id` / `external_reference`. Same body in both cases. |
| **409** | `external_reference_conflict` | Same create `external_reference` with a different body. Not a commercial duplicate.      |
| **409** | `revision_conflict`           | Contact correction used a stale `expected_revision`.                                     |
| **409** | `idempotency_conflict`        | The same `operation_idempotency_key` was reused with a different body.                   |
| **409** | `concurrent_promotion`        | Another promotion is already in progress or linked.                                      |
| **413** | `payload_too_large`           | Body exceeds the 64 KiB limit. Nothing is persisted.                                     |
| **422** | `validation_error`            | JSON parsed but failed the level schema (unknown field, range, or evidence).             |
| **429** | `rate_limited`                | Identity, IP, or failed-auth limiter. See `Retry-After`.                                 |
| **503** | `service_unavailable`         | Temporary upstream or platform unavailability. Retry with backoff.                       |

Commercial `duplicate_not_accepted` is **not** HTTP 409. It arrives asynchronously on the status object after a **202** create.

## Support

Send the `X-Request-Id` response header, `submission_id`, `external_reference`, and `environment`. Do not send the raw request body in tickets that may be forwarded to shared channels.