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 one of: (1) session.noteText, (2) session.diagnosisCodes + session.procedureCodes, or (3) session.diagnosisCodes + session.durationMinutes.

"Duplicate externalSessionId" (409) — You already submitted a session with this externalSessionId. The response includes the existing sessionId so you can track it instead. If you need to correct it, use the PATCH session endpoint.

"Session cannot be updated" (409) — The session has already been submitted to a payer and can no longer be modified. Only sessions in processing status can be updated via PATCH.

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