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

# Errors

> Standard error envelope and status codes used across all Idunox Platform endpoints.

## Error envelope

All error responses use a consistent JSON envelope:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid canonical Type A submission payload",
    "requestId": "d6388f40-c7c0-4037-bdd9-2c3f3a4f02fa",
    "correlationId": "hy-2026-05-25-001",
    "details": {
      "formErrors": [],
      "fieldErrors": {
        "subject.history.smoking.currentFrequency": [
          "must be omitted for former smokers"
        ],
        "sourceMetadata.markerRanges.ALT": [
          "Expected string, received object"
        ]
      }
    }
  }
}
```

| Field           | Type            | Description                                  |
| --------------- | --------------- | -------------------------------------------- |
| `code`          | string          | Machine-readable error code                  |
| `message`       | string          | Human-readable description                   |
| `requestId`     | string          | Idunox-generated request identifier          |
| `correlationId` | string          | Echoes `x-correlation-id` when supplied      |
| `details`       | object or array | Validation context (shape depends on `code`) |

### Canonical body validation (`VALIDATION_ERROR`)

`POST /v1/submissions` returns **`VALIDATION_ERROR`** when the JSON does not match `canonical_submission_v1`. Details use Zod flatten format:

* `details.formErrors` — top-level issues
* `details.fieldErrors` — map of JSON paths to message arrays

Common fixes:

* Map questionnaire into `subject.*` (not legacy `markers.healthQuestionnaireMarkers`)
* Use structured `sourceMetadata.markerRanges` objects `{ unit, lowerBound, upperBound }` (not display strings)
* Omit `currentFrequency` for `smoking.status: "former"`
* Align `familyHistory.*.aliveStatus` with `currentAge` / `deathAge` (only send the age that applies)

See [Canonical submission JSON](/platform/canonical-submission).

### Blood panel validation (`SUBMISSION_VALIDATION_ERROR`)

When the 14-marker panel fails code/unit/bounds checks, the code may be **`SUBMISSION_VALIDATION_ERROR`** with `details` as an array:

```json theme={null}
{
  "error": {
    "code": "SUBMISSION_VALIDATION_ERROR",
    "message": "Blood marker submission failed validation.",
    "details": [
      { "field": "markers", "message": "Expected 14 blood markers for this panel." },
      { "field": "markers.ALT.unit", "message": "Unit must match preset for ALT (expected U/L)." }
    ]
  }
}
```

### Partner id mismatch (`PARTNER_ID_MISMATCH`)

`403` when `partnerId` in the body does not match the authenticated credential UUID.

## HTTP status codes

| Status | Meaning                                                                               |
| ------ | ------------------------------------------------------------------------------------- |
| `200`  | Request succeeded                                                                     |
| `202`  | Submission accepted and queued                                                        |
| `204`  | Success with no body (e.g. auth probe)                                                |
| `400`  | Bad request — validation failure                                                      |
| `401`  | Missing or invalid API key                                                            |
| `403`  | Forbidden — e.g. `partnerId` mismatch                                                 |
| `404`  | Resource not found or different account                                               |
| `409`  | Idempotency conflict — same key, different body hash                                  |
| `429`  | Rate limit exceeded                                                                   |
| `500`  | Internal server error — include `requestId` / `correlationId` when contacting support |

## Partner-safe notices

`GET /v1/results` may include `notices[]` on outcomes with informational messages. Notices are **not** errors. They never contain internal model codes or stack traces.

## x-correlation-id

Include a unique `x-correlation-id` on every `POST`. The platform binds it to logs and error responses. Provide it when reporting issues to `partner@idunox.com`.