Errors, limits and request ids

Every error the API answers has one of two shapes, decided by where the request went:

Under the FHIR base (/v1/fhir/r4), a FHIR OperationOutcome, sent as application/fhir+json. A FHIR client reads it like any other resource.
Everywhere else, an RFC 9457 problem, sent as application/problem+json.

Each service’s page lists the statuses that service answers for its own reasons. This page covers the ones every service shares.

The two shapes

{
  "type": "https://docs.haau3.com/errors#invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The query parameters are not valid. Each entry in issues names one.",
  "instance": "urn:uuid:0b6f2d4e-8c1a-4e3b-9f5d-2a7c6e1b4d90",
  "issues": [
    { "path": ["status"], "message": "Invalid option: expected one of \"free\"|\"busy\"|\"busy-unavailable\"|\"busy-tentative\"" }
  ]
}

{
  "resourceType": "OperationOutcome",
  "issue": [
    {
      "severity": "error",
      "code": "not-found",
      "details": {
        "text": "No resource, operation, or interaction is served at this path. GET [base]/metadata lists what this base serves."
      }
    }
  ]
}

A problem has these members:

Member	What it holds
`type`	A link to this page’s section for the problem. Branch on this, not on the text.
`title`	A short summary. It is the same for every problem of one type.
`status`	The HTTP status code, the same as the response’s.
`detail`	What went wrong this time, and how to correct it. It is written for people, so do not parse it.
`instance`	This request’s id, written `urn:uuid:<id>`: the same id as the response’s `X-Request-Id` header. See request ids.
`issues`	On a `400` only: one entry per parameter that is not valid, each with a `path` naming it and a `message` saying why.

Problems may gain members over time. Ignore any member you do not recognise. An OperationOutcome says the same things in FHIR’s terms: each entry in issue carries a code from FHIR’s issue types and a details.text saying what went wrong.

Statuses every service shares

Status	Problem `type`	`OperationOutcome` code	Send it again?
`400`	`invalid-request`	varies by service	No. Correct the request first.
`401`	`unauthorized`	`login`	No. Send a valid key.
`404`	`not-found`	varies by service	No.
`405`	`method-not-allowed`	`not-supported`	No. Use a method the `Allow` header lists.
`406`	`not-acceptable`	`not-supported`	No. Accept JSON.
`413`	none: only the FHIR base reads a body	`too-long`	No. Send less: see limits.
`415`	`unsupported-media-type`	`not-supported`	No. Send the body as JSON.
`429`	`rate-limited`	`throttled`	Yes, after the `Retry-After` time, which for a monthly limit can be weeks.
`500`	`server-error`	`exception`	Once, after a short wait.
`503`	`unavailable`	varies by service	Yes, after the `Retry-After` time when one is sent.

A 502, a 504, and some 503s come from a source behind a service: see when a source fails.

Invalid request

400. Something in the request is not valid: a parameter, its value, or the body. Outside the FHIR base, issues names each parameter at fault. On the FHIR base, the OperationOutcome names it. A parameter the path does not take, or one sent twice, is a 400 too: see parameters.

Unauthorized

401. No API key was sent, or the key sent was not recognised. The detail says which, and the response carries WWW-Authenticate: Bearer realm="api.haau3.com", with error="invalid_token" added when a key was sent. See Authentication.

Not found

404. Nothing is served at this path, or the record asked for does not exist. A path that does not exist anywhere is a 404 in the base’s shape: GET /openapi.json lists every path the API serves, and GET /v1/fhir/r4/metadata lists what the FHIR base serves.

Method not allowed

405. The path exists, but does not take the method sent. The Allow header lists the methods it does take, for example Allow: GET, HEAD, OPTIONS.

Not acceptable

406. The request asked for a format the API does not answer in. Every answer is JSON: see formats. On the FHIR base it is also the answer to a FHIR release this endpoint does not serve.

Unsupported media type

415. A body was posted without saying it is JSON. Send Content-Type: application/fhir+json (application/json is accepted too).

Rate limited

429. Your organization reached one of its plan’s limits, which take effect on 2026-11-01. Two can answer, each with a Retry-After header in seconds and a sentence naming the limit:

Requests a minute, on every plan. The wait runs to the start of the next minute, so it is at most 60 seconds. Send the request again after it.
Requests a month, on the Developer plan only. The wait runs to 00:00 UTC on the 1st of the next month, which can be weeks away, so don’t send it again automatically. Change plan to keep going now.

Each plan’s numbers are in limits.

Server error

500. The server failed to process the request. Send it again once, after a short wait. If it fails again, the request is one we have to fix.

Unavailable

503. The service cannot answer right now. When the response carries Retry-After, wait that many seconds before sending the request again. On the FHIR base, the OperationOutcome says what is unavailable: a source rate limiting requests is coded throttled (see when a source fails), and a source this deployment does not have is coded not-supported. Any request can get a 503 with Retry-After when its API key could not be checked just now, coded transient on the FHIR base. So can a Scheduling request when the scheduling database is unavailable or slow. Neither says anything about the request: send it again after the wait.

When a source fails

Four services answer from a source behind them: terminology (LOINC), the provider directory (CMS’s National Provider Directory), Questionnaires (LOINC, and a form’s own publisher) and Plan Benefits’ $in-network (the provider directory). When the source fails, the service says so in an OperationOutcome. It never answers with a guess, an empty result or “not found” in place of the answer it could not get.

Status	What happened	Send it again?
`502`	The source refused or failed the request, or answered in a form the service could not read.	Once, after a short wait.
`503`	The source is rate limiting requests. The code is `throttled`, and `Retry-After` says how many seconds to wait: 2, or longer when the source asked for longer.	Yes, after the `Retry-After` time.
`504`	The source did not answer in time.	Once, after a short wait. A search that is slow because of what it asks will be slow again, so narrow it first.

Before answering any of these, the service has already asked its source a second time when that could help, after waiting a moment, and waited as long as the source asked when that was 5 seconds or less. Inside a batch Bundle, a throttled entry answers 503 but carries no Retry-After, because an entry has no headers of its own. Wait 2 seconds and send that entry again.

Methods

405 and Allow. A method a path does not take answers 405 with an Allow header naming the methods it does take.
HEAD answers exactly like GET on every path that takes GET, without the body.
OPTIONS answers 204 with the Allow header and no body. Like every request under /v1, it needs an API key.

Inside a batch Bundle, an entry gets the answer the same request would get on its own. A 405 there has no header to carry, so its OperationOutcome names the methods instead.

Formats

Every answer is JSON. A request whose Accept header admits no JSON gets a 406 rather than JSON it did not ask for. These admit JSON: application/json, application/fhir+json, application/json+fhir, text/json, application/* and */*, with any parameters. No Accept header at all is fine too. On the FHIR base, _format takes precedence over Accept: json, application/json, application/fhir+json, application/json+fhir and text/json are served, and any other value is a 406. A POST to the FHIR base must say its body is JSON, with Content-Type: application/fhir+json or one of the types above. A body sent without one gets a 415.

Limits

Every API on the platform today is included in every plan. Free to start on the Developer plan. From 2026-11-01, each plan has two limits, counted for your organization across all of its keys:

Plan	Requests a month	Requests a minute	Past the month’s allowance
Developer	1,000	60	Stops: a `429` until the 1st of the next month
Team	50,000	600	Keeps working, with no extra charge
Scale	500,000	3,000	Keeps working, with no extra charge

A month is a calendar month in UTC. A request counts once, a batch included. A 5xx, a 401 and a 429 do not count. If an organization keeps going past its allowance, we’ll get in touch about a plan that fits. The minute limit counts every request sent with your organization’s keys, and a request past it is a 429 on every plan (see rate limited). Until 2026-11-01 no request is refused for a limit. Your organization’s count for this month is on the dashboard’s Overview and Usage pages at platform.haau3.com, and the plans are on pricing. Every request also has bounds of its own, whatever the plan:

What	Limit	Past it
Entries in a batch `Bundle`	100	`400`, coded `too-long`. Send the entries in smaller batches.
A request body on the FHIR base: a batch, or an operation’s `Parameters`	1 MiB	`413`, coded `too-long`.
The body of `$reconcile-medications`	16 MiB	`413`, coded `too-long`.
Entries in the `Bundle`, or parameters in the `Parameters`, of `$reconcile-medications`	50,000	`400`, coded `too-long`. Send one patient’s records per request.
`property` on `CodeSystem/$lookup`, the query and the body together	100	`400`, coded `too-long`.
How long a batch runs	60 seconds	Each entry still running answers `504` inside the batch’s `200`. Send it again on its own or in a smaller batch.
How long `$reconcile-medications` runs	20 seconds	`504`.

The largest batch most callers need is far smaller: a batch of 50 lookups is a few kilobytes. A source or store that does not answer in time is a 504. When your API key could not be checked, or the scheduling database is unavailable or slow, the answer is a 503 with Retry-After (see unavailable). Neither says anything about your request, so send it again after a short wait. A first call after a quiet period can take a few seconds. Calls after it are faster.

Paging

A list that can be long comes back a page at a time, in one of four ways, each its service’s own:

Where	Page size	Next page	Also
Scheduling `/slots` and `/provider-locations`	`limit`, 1 to 100, 25 by default	`offset`	`total` counts every match.
Provider directory searches	`_count`, 1 to 100	Follow the `next` link as given	Its `page` cursor is opaque and expires: an expired one is a `400`. See paging.
`InsurancePlan` searches	`_count`, 1 to 50, 10 by default	Follow the `next` link as given	`total` on every page. A `410` means the plans changed: start the search again. See paging.
`ValueSet/$expand` on a value set this service hosts	`count`	`offset`	An expansion from its own source comes back whole.

Every other list comes back whole in one answer: Scheduling’s /publishers, /service-types and /specialties, a Questionnaire search (with total), $counties and $in-network.

Caching and compression

Every JSON answer is compressed with gzip when the request’s Accept-Encoding allows it, and says so in Content-Encoding. Most HTTP clients ask for this and undo it without being told. The Slot Publisher’s NDJSON files are sent uncompressed.

What	`Cache-Control`	Also
`GET /openapi.json`	`public, max-age=300`	An `ETag`. Send it back in `If-None-Match` for a `304` when the spec has not changed.
`GET /v1/fhir/r4/metadata`	`private, max-age=300`	An `ETag`, as above. An answer that says a store could not be read just now is `no-store`.
`$reconcile-medications`	`no-store`	On every answer, errors included: it carries patient data.

Parameters

Each operation takes the parameters the API reference lists for it, and no others. A parameter it does not take gets a 400 that names it, rather than an answer as if it had not been sent, so a misspelt filter never comes back as an unfiltered answer that looks right. Every parameter at fault is named at once: outside the FHIR base, one entry in issues each, its path naming the parameter; on the FHIR base, one OperationOutcome issue each, its expression naming the parameter. The message lists the parameters the operation does take.

{
  "type": "https://docs.haau3.com/errors#invalid-request",
  "title": "Invalid request",
  "status": 400,
  "detail": "The query parameters are not valid. Each entry in issues names one.",
  "instance": "urn:uuid:0b6f2d4e-8c1a-4e3b-9f5d-2a7c6e1b4d90",
  "issues": [
    { "path": ["startafter"], "message": "Not supported. Supported parameters: status, publisher, serviceTypeCode, npi, specialty, appointmentType, acceptingPatients, isVirtual, city, state, startAfter, startBefore, includePast, providerLocationKey, limit, offset." }
  ]
}

A parameter sent twice is refused the same way, unless the API reference says it repeats, as property does on CodeSystem/$lookup. Scheduling’s lists (serviceTypeCode, npi and specialty) are one parameter whose values are separated by commas.
A read (GET [base]/[type]/[id]), a batch and $reconcile-medications take no parameters. A batch entry carries its own in its request.url, and each entry is checked as the same request on its own would be.
_format belongs to the FHIR base and is taken on every path there (see formats). Outside the FHIR base it is not a parameter, and is refused like any other.
A Parameters body, when an operation is called with POST, follows the same rules: a parameter the operation does not take is refused, each parameter needs a name and a value, and a name sent both in the URL and in the body counts as sent twice.

Names are checked before values. Once every parameter is one the operation takes, a value that is not valid is named in the same way.

Request ids

Every response carries an X-Request-Id header holding a UUID that haau3 gave the request, errors included. A problem carries the same id as its instance, written urn:uuid:<id>. On the FHIR base the id is in the header only, and the OperationOutcome is unchanged. To ask about a response, email hello@haau3.com with its X-Request-Id and the time you sent the request. haau3 keeps its record of a request for 30 days, so ask within that time. You can also send an id of your own. Put a UUID in the request’s X-Request-Id header, and the response carries it back in X-Correlation-Id, beside haau3’s id. haau3 keeps your id with its record of the request, so a question can name either one. A value that is not a UUID is ignored: it is not kept, and it does not come back.

GET /v1/fhir/r4/metadata HTTP/1.1
Authorization: Bearer <key>
X-Request-Id: 3b8e7a52-9c41-4f0e-b6d2-7a1c5e9f0d84

HTTP/1.1 200 OK
X-Request-Id: 0b6f2d4e-8c1a-4e3b-9f5d-2a7c6e1b4d90
X-Correlation-Id: 3b8e7a52-9c41-4f0e-b6d2-7a1c5e9f0d84

Changes

Changes a caller can see are recorded on the changelog from 2026-11-01.

Get started

Build

Scheduling

Terminology

Provider directory

Questionnaires

Plan Benefits

MedList

API reference

Errors, limits and request ids

The two shapes

Statuses every service shares

Invalid request

Unauthorized

Not found

Method not allowed

Not acceptable

Unsupported media type

Rate limited

Server error

Unavailable

When a source fails

Methods

Formats

Limits

Paging

Caching and compression

Parameters

Request ids

Changes

​The two shapes

​Statuses every service shares

​Invalid request

​Unauthorized

​Not found

​Method not allowed

​Not acceptable

​Unsupported media type

​Rate limited

​Server error

​Unavailable

​When a source fails

​Methods

​Formats

​Limits

​Paging

​Caching and compression

​Parameters

​Request ids

​Changes

The two shapes

Statuses every service shares

Invalid request

Unauthorized

Not found

Method not allowed

Not acceptable

Unsupported media type

Rate limited

Server error

Unavailable

When a source fails

Methods

Formats

Limits

Paging

Caching and compression

Parameters

Request ids

Changes