Skip to main content

​
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"
        ]
      }
    }
  }
}
FieldTypeDescription
codestringMachine-readable error code
messagestringHuman-readable description
requestIdstringIdunox-generated request identifier
correlationIdstringEchoes x-correlation-id when supplied
detailsobject or arrayValidation 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

StatusMeaning
200Request succeeded
202Submission accepted and queued
204Success with no body (e.g. auth probe)
400Bad request — validation failure
401Missing or invalid API key
403Forbidden — e.g. partnerId mismatch
404Resource not found or different account
409Idempotency conflict — same key, different body hash
429Rate limit exceeded
500Internal 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.