Error codes | Mantys Eligibility API

Headers are checked in this order, and the first failure is the one returned: the Bearer prefix, the key, the clinic, then the tenant.

HTTP	`code`	When	What to do
401	`MALFORMED_AUTH_HEADER`	`X-Api-Key` lacks the `Bearer` prefix (case-sensitive)	Send `Bearer <key>`
401	`INVALID_API_KEY`	Key not recognised	Check the key
403	`CLINIC_NOT_AUTHORIZED`	Key is valid but not for this `X-Clinic-Id`	Use a clinic on your key, or ask Mantys to add it
403	`UNKNOWN_TENANT`	`X-Client-ID` not recognised	Check your tenant id
403	`UAT_TEST_IDS_ONLY`	Only on a Mantys UAT server, which answers test IDs and nothing else: a real check or any other request	Use a test ID there, and the production host for real checks
422	`VALIDATION_FAILED`	Missing header, malformed JSON, unknown field, bad query parameter or cursor	Fix the field named in `details`
400	`VALIDATION_FAILED`	The payer does not accept the request (see `details`)	Fix every item in `details`, then resend
400	`VISIT_TYPE_UNDERIVABLE`	Only on accounts whose visit type comes from the encounter: no known value in the encounter fields	Send `visit_type`, or a recognised encounter value
400	`ROUTING_NOT_CONFIGURED`	Appointment checks not set up for your account	Contact Mantys
400	`CANCELLATION_NOT_SUPPORTED`	The check's payer requests are all with payers that cannot be cancelled	None; cancel at the payer directly
404	`CHECK_NOT_FOUND`	Unknown id, or another clinic's check	Check the id and `X-Clinic-Id`
409	`CHECK_NOT_CANCELLABLE`	Check already cancelled	None needed
409	`NOT_SUBMITTED_TO_PAYER`	No row on the check carries a payer reference	If the check is still running, retry once it progresses; otherwise nothing to cancel
500	`INTERNAL_ERROR`	Unexpected error on our side	Retry later; send Mantys the `request_id`

On malformed JSON, the 422's details[].field is the character position where parsing failed (for example "23"), and its message is "JSON decode error".

details[].code on a 400:

`details[].code`	Meaning
`MISSING_REQUIRED_FIELD`	`doctorId`/`doctorName` is missing on `INS026`, `D004`, `INS078` or `TPA023`. Reported with `field: "doctor_id"`. An empty value is not "missing": an empty `visit_type` is `UNSUPPORTED_VISIT_TYPE` where a value is needed
`UNKNOWN_TPA`	`tpa_name` is not a payer code we support
`UNSUPPORTED_ID_TYPE`	This payer does not accept this `id_type`; `field` is `identifiers[N].id_type`
`UNSUPPORTED_VISIT_TYPE`	This payer does not accept this `visit_type`; see Visit types by payer
`INVALID_EMIRATES_ID`	An `EMIRATESID` entry is not a valid Emirates ID format; `field` is `identifiers[N].id_value`
`VISIT_TYPE_UNDERIVABLE`	An encounter field named no known value; `field` is `extra_args.<name>` (encounter accounts only)
`VALIDATION_FAILED`	A test ID that names no known case, or a test ID sent to `POST /v4/appointment-checks`

New codes may be added. Treat an unknown code by its HTTP status.