Errors

Error envelope

All error responses use a consistent JSON envelope:

{
  "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.

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:

{
  "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.

Get Started

Input Data Guide

API Platform

Error envelope

Canonical body validation (`VALIDATION_ERROR`)

Blood panel validation (`SUBMISSION_VALIDATION_ERROR`)

Partner id mismatch (`PARTNER_ID_MISMATCH`)

HTTP status codes

Partner-safe notices

x-correlation-id

​Error envelope

​Canonical body validation (VALIDATION_ERROR)

​Blood panel validation (SUBMISSION_VALIDATION_ERROR)

​Partner id mismatch (PARTNER_ID_MISMATCH)

​HTTP status codes

​Partner-safe notices

​x-correlation-id

Error envelope

Canonical body validation (`VALIDATION_ERROR`)

Blood panel validation (`SUBMISSION_VALIDATION_ERROR`)

Partner id mismatch (`PARTNER_ID_MISMATCH`)

HTTP status codes

Partner-safe notices

x-correlation-id