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

# Error Handling

> Error response format the Ledger API returns and what each status code means for callers.

Application error responses follow [RFC 9457 — Problem Details for HTTP APIs](https://www.rfc-editor.org/rfc/rfc9457) and are served as `application/problem+json`. The body always contains `status`, `title`, and `instance`. `detail` and `violations` appear on specific variants below.

## Validation errors (400)

Validation failures return a list of `violations` so you can highlight every problem at once. No `detail` on this variant.

```json theme={null}
{
  "status": 400,
  "title": "Bad Request",
  "instance": "/v1/parties",
  "violations": [
    { "field": "firstName",                "in": "body",   "message": "must not be blank" },
    { "field": "taxIdentifications[0].tin", "in": "body",  "message": "must be a valid TIN" },
    { "field": "Idempotency-Key",          "in": "header", "message": "must not be blank" }
  ]
}
```

A missing or malformed request body returns the simpler shape with a `detail` field and no `violations`:

```json theme={null}
{
  "status": 400,
  "title": "Bad Request",
  "detail": "HTTP 400 Bad Request",
  "instance": "/v1/parties"
}
```

## Resource not found (404)

The resource does not exist, or the path or identifier could not be parsed.

```json theme={null}
{
  "status": 404,
  "title": "Not Found",
  "detail": "Resource not found",
  "instance": "/v1/accounts/00000000-0000-0000-0000-000000000000"
}
```

## Method not allowed (405)

The endpoint exists but does not accept the HTTP method used.

```json theme={null}
{
  "status": 405,
  "title": "Method Not Allowed",
  "detail": "HTTP 405 Method Not Allowed",
  "instance": "/v1/parties"
}
```

## Content negotiation (406, 415)

The `Accept` or `Content-Type` header is incompatible with what the endpoint produces or consumes.

```json theme={null}
{
  "status": 406,
  "title": "Not Acceptable",
  "detail": "The accept header value did not match the value in @Produces",
  "instance": "/v1/parties/{id}"
}
```

```json theme={null}
{
  "status": 415,
  "title": "Unsupported Media Type",
  "detail": "The content-type header value did not match the value in @Consumes",
  "instance": "/v1/parties"
}
```

## Server errors (500)

An unexpected condition prevented the request from completing. Reads can be retried freely; for state-changing requests, retries are safe only when the original request included an `Idempotency-Key`.

```json theme={null}
{
  "status": 500,
  "title": "Internal Server Error",
  "instance": "/v1/accounts"
}
```

## Status code summary

| Status        | Meaning                                                                                                                                 |
| ------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `202`         | Request accepted for asynchronous processing. Track outcome via `correlationId` and webhooks.                                           |
| `400`         | Validation failure (`violations` present) or malformed request body (`detail` present).                                                 |
| `401`         | Missing or invalid bearer token.                                                                                                        |
| `403`         | IP not whitelisted, or the bearer token lacks the permission required for the operation.                                                |
| `404`         | Resource not found, unknown route, or path parameter could not be parsed.                                                               |
| `405`         | HTTP method not supported on this endpoint.                                                                                             |
| `406`         | The `Accept` header is incompatible with what the endpoint produces.                                                                    |
| `415`         | The `Content-Type` of the request body is incompatible with what the endpoint consumes.                                                 |
| `500`         | Internal server error. Reads can be retried freely; state-changing requests are safe to retry only with the original `Idempotency-Key`. |
| `502` / `503` | Edge proxy error. Body and `Content-Type` are not guaranteed to follow RFC 9457 — do not parse.                                         |