Errors

Error format

Simple errors return a single message:

{
  "error": "Description of what went wrong"
}

Validation errors on the Submit Session endpoint include an issues array with the specific field paths and messages:

{
  "error": "Validation failed",
  "issues": [
    { "path": "patient.dateOfBirth", "message": "patient.dateOfBirth is required for claim submission" },
    { "path": "patient.address.state", "message": "patient.address.state must be a 2-letter state code" }
  ]
}

HTTP status codes

Common mistakes

"Validation failed" (400) — Check the issues array for the exact fields that need fixing. Common causes:

• Missing patient.address — address is required for claim submission.
• Missing patient.dateOfBirth or patient.gender — both are required for claims.
• Neither codes nor note provided — you must send diagnosisCodes + procedureCodes, or noteText, or all three.

"Provider NPI not found" (404) — You need to onboard the provider before submitting sessions under their NPI.

"Invalid or missing API key" (401) — Make sure your Authorization header is formatted as Bearer <your-api-key>.