Getting started

Errors & rate limits

Every refusal is a plain sentence that says what happened and what fixes it. Errors are JSON with a single envelope; machine-readable codes appear where a program should branch.

The error envelope#

{
  "error": "More than one lot matches that identity. Provide lot_id.",
  "code": "ambiguous_lot",          // present when a program should branch on it
  "candidateLotIds": ["LOT-…", "LOT-…"]  // extra fields when they help fix the request
}

Status codes#

Rate limits#

Each API key has its own allowance on each endpoint, per minute, wherever it calls from. Beyond it the answer is 429, "code": "rate_limited", with Retry-After, retryAfterSeconds in the body, and X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset headers. A second, per-address ceiling of the same size also applies on each endpoint.

• Per key, per minute, by plan: each /v1 endpoint allows 600 requests per key per minute on a paid plan, and 1,200 with supported API automation (Operations); beyond it, 429 Rate limit exceeded. /v1 keys need a paid plan.
• The buyer read API: 300 requests a minute per workspace, free, counted apart for test and live keys; 600 on a paid plan and 1,200 with supported API automation. Every answer carries X-RateLimit-Limit.
• Concurrency on checks: POST /v1/check reads a whole document, so each key may have a small number of checks in flight at once (4 by default). Beyond that the request is shed immediately with 429, "code": "concurrency_limited", a Retry-After header, and retryAfterSeconds in the body: nothing is queued, nothing is lost, retry after the stated delay.
• Metering: document reads are metered per key per day; the workspace shows usage.

Release refusal codes#

Passport issuance enforces the release rules on every path. These are the codes POST /v1/passports can answer, with 409 unless stated; each refusal's sentence names its fix. Before a purchased lot issues anything: it is cleared, carries no hold or recall, a certificate has been read against it, and a named person has reviewed it.

phi_in_order_ref and phi_in_customer_ref answer 400; release_policy_error answers 500. A seal batch refuses an entry that reads like patient information with 400 phi_in_order_refs, and a test key with 403 test_mode_unsupported.

Signing refusals#

A signature in the workspace (a lot review, a hold, the 503A basis, a by-hand release, a Seal assignment, a quality unit decision) is made by a signed-in person, never by an API key. The routes that write one answer 428 when the person must confirm who they are first; nothing is recorded, and the same request succeeds once they have.

Each signature records how it was made: reauthenticated, and reauthMethod password or authenticator.

Retries and idempotency#

• On 429, honor Retry-After when present; otherwise back off and retry. Shed requests were never processed.
• Passport issuance is idempotent per order: re-issuing the same order returns the existing record with reused: true rather than a duplicate.
• Seal batches are not idempotent: every successful POST /v1/seal-batches mints new serials. Retry only requests that failed.