Guides

The shape of every error, which failures are safe to retry, and how an Idempotency-Key keeps a retried request from running twice.

Every error has the same shape, a stable error code you can branch on, and a request ID you can quote. Read this page before you write retry logic: some failures are replayed exactly, and some must be retried with a new key.

The error shape#

{
  "error": "INVALID_REQUEST",
  "message": "The request is not valid.",
  "errors": [
    { "field": "limit", "code": "invalid_value", "message": "limit must be a whole number from 1 to 100." }
  ],
  "request_id": "req_..."
}

• error is a stable code. Branch on it, never on message.
• message is a plain sentence for a person.
• errors lists every problem found in a request that was not valid, so you can fix them all in one go. It is empty for every other error. Each item has a field (a dotted path such as subscriber.member_id, or null for the request as a whole), a stable code, and a message. A message never repeats the value you sent.
• request_id is the ID of the request. The same ID is in the x-request-id response header of every reply, errors and successes. Quote it when you contact support.

The field code is one of required, invalid_type, too_short, too_long, too_small, too_big, invalid_format, invalid_value, unknown_field, invalid_body, invalid, or, for an eligibility request, one of the findings listed in Eligibility.

curl "https://sandbox.myclaimhouse.com/api/v1/payers?limit=500" -H "Authorization: Bearer $CLAIMHOUSE_KEY"

Error codes#

An eligibility check that is rejected, unavailable or failed carries the check itself next to the error, so you can always find the check an error is about. See Eligibility.

Which failures to retry#

A request that fails after it has started is never run a second time by a retry. That is the next section.

Idempotency#

Send an Idempotency-Key header with every POST and PATCH. A request without one is refused with 400 IDEMPOTENCY_KEY_REQUIRED.

• The key is 1 to 255 printable ASCII characters, with no spaces. A UUID is a good choice. A key that is not of that form is refused with 400 IDEMPOTENCY_KEY_REQUIRED, like a missing one.
• Never put patient information in a key. Keys are stored and kept in the request log.
• The same key with the same method, path, query and body returns the stored answer, with the header idempotent-replayed: true. The check is not made again and not billed again. A replay is the stored body, so its request_id is the first request's; the x-request-id header is the new request's.
• The same key with anything different is refused with 422 IDEMPOTENCY_KEY_REUSED.
• While the first request is still running, a duplicate waits up to 10 seconds, then answers 409 IDEMPOTENCY_KEY_IN_USE.
• Stored answers are kept for 24 hours, then deleted. After that, the same key starts a new request.

The outcome is final once the request has started#

Once Claim House has started a request, its outcome is final, including a failure. A retry with the same key replays that stored 502, 500 or 504; it does not run the request again, because the request may already have reached a payer.

So the rule is: a retry after no response reuses the key; a retry after an error response is a new attempt and uses a new key. A request that failed before it started (for example 401 UNAUTHORIZED) can be sent again with the same key.

After a timeout#

A 504 TIMEOUT means Claim House stopped waiting, not that nothing happened. For an eligibility check, find out before you send it again. Use the request_id of the 504, or your Idempotency-Key:

curl "https://sandbox.myclaimhouse.com/api/v1/eligibility?idempotency_key=my-key-1" -H "Authorization: Bearer $CLAIMHOUSE_KEY"

Each check carries the request_id and the idempotency_key of the request that made it. If a check is there, read its answer: if its state is still pending, it is still running, so read it again shortly. If no check is there, send the check again with a new key.

This needs a key with read permission. An integration that submits checks with a submit-only key should keep a separate read key for this lookup.

Request size#

A request body over 1 MB is refused with 413 PAYLOAD_TOO_LARGE, before anything is recorded. An attachment upload has its own limit (see Attachments), and one whose body stops arriving for 15 seconds is refused with 408 REQUEST_TIMEOUT.