Errors

ClinikAPI uses standard HTTP status codes and returns structured error responses.

Error Response Format

{
  "error": "Validation Error",
  "code": "VALIDATION_ERROR",
  "requestId": "req_k8f3a7x2",
  "issues": [
    {
      "severity": "error",
      "code": "invalid",
      "diagnostics": "firstName: Required"
    }
  ]
}

HTTP Status Codes

Status	Meaning
`400`	Bad Request — malformed JSON or invalid parameters
`401`	Unauthorized — missing or invalid API key
`403`	Forbidden — key doesn’t have required scope
`404`	Not Found — resource doesn’t exist or belongs to another tenant
`409`	Conflict — resource version conflict
`422`	Validation Error — request body failed Zod validation
`429`	Rate Limited — too many requests for your plan
`500`	Internal Error — something went wrong on our end

Error Codes

Code	Description
`UNAUTHORIZED`	Missing `x-api-key` header
`INVALID_KEY_FORMAT`	Key doesn’t match `clk_live_` or `clk_test_` pattern
`INVALID_KEY`	Key not found in the database
`KEY_REVOKED`	Key has been revoked
`KEY_EXPIRED`	Key has passed its expiration date
`VALIDATION_ERROR`	Request body failed schema validation
`INVALID_JSON`	Request body was not valid JSON
`METHOD_OVERRIDE_REJECTED`	Request carried an HTTP method-override header
`SANDBOX_QUOTA_EXCEEDED`	Monthly sandbox (test-key) allowance used up
`RATE_LIMITED`	Plan request limit exceeded
`NOT_FOUND`	Resource not found
`INTERNAL_ERROR`	Unexpected server error

Method Override Is Not Supported

Send the HTTP method you mean. Requests carrying X-HTTP-Method-Override, X-HTTP-Method or X-Method-Override are rejected with 400 and METHOD_OVERRIDE_REJECTED, whatever the value. A request whose real method disagrees with the one being executed breaks two guarantees this API depends on: that a GET never modifies data, and that the audit log records the operation that actually happened. The SDK never sends these headers.

SDK Error Handling

The SDK throws typed errors that you can catch:

import { Clinik } from '@clinikapi/sdk';

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!);

try {
  const { data } = await clinik.patients.create({
    firstName: 'Jane',
    lastName: 'Doe',
  });
} catch (err) {
  if (err.name === 'ClinikValidationError') {
    console.error('Validation issues:', err.issues);
  } else if (err.name === 'ClinikRateLimitError') {
    console.error('Rate limited. Retry after:', err.retryAfter, 'seconds');
  } else if (err.name === 'ClinikApiError') {
    console.error('API error:', err.code, err.message);
    console.error('Request ID:', err.requestId);
  }
}

Automatic Retries

The SDK automatically retries on 5xx errors and 429 (rate limit) responses with jittered exponential backoff:

Default: 2 retries
Backoff: random jitter up to min(1000 * 2^attempt, 10000) ms
Configurable via retries option:

const clinik = new Clinik(process.env.CLINIKAPI_SECRET_KEY!, {
  retries: 3,      // max retry attempts
  timeout: 15000,  // request timeout in ms
});

Rate Limits

The rate limit is a per-minute ceiling on how fast you can call the API. The window is 60 seconds and rolling — exhaust it and the next minute starts fresh.

Plan	Requests per minute
Sandbox (free)	100
Starter	200
Pro	1,000
Team	5,000
Enterprise	10,000

It applies to all traffic, test and live alike, and is shared across every key in the organization. Exceeding it returns 429 with code RATE_LIMITED. The current state comes back on every response:

Header	Description
`X-RateLimit-Limit`	Requests allowed per minute on your plan
`X-RateLimit-Remaining`	Requests remaining in the current minute
`X-RateLimit-Reset`	Seconds until the window resets

The rate limit and the monthly quota are different limits that both return 429. The rate limit is about speed (per minute); the quota below is about volume (per month). Check the error code to tell them apart: RATE_LIMITED versus MONTHLY_QUOTA_EXCEEDED.

The SDK exposes these in meta:

const { data, meta } = await clinik.patients.search();
console.log(meta.rateLimitRemaining); // 498

Monthly Quotas & Overage

Separate from the per-minute rate limit, every organization has one shared monthly request pool — all API keys and all sub-organizations draw from the same quota. On paid plans only live requests are billable; test traffic is metered but free. On the Sandbox plan every request counts. The pool resets on the 1st of each month (UTC).

Plan	Included requests per month	Counts test traffic?
Sandbox (free)	1,000	Yes — every request
Starter	60,000	No — live only
Pro	600,000	No — live only
Team	3,000,000	No — live only
Enterprise	Unlimited	No — live only

The sandbox pool

Test traffic is free, but not unlimited. Every paid plan gets a separate monthly sandbox allowance equal to its live allowance — Pro includes 600,000 live requests and 600,000 sandbox requests. They are independent pools: spending one never touches the other.

Plan	Live requests	Sandbox requests
Sandbox (free)	—	1,000 (the shared pool above)
Starter	60,000	60,000
Pro	600,000	600,000
Team	3,000,000	3,000,000
Enterprise	Unlimited	Unlimited

Sandbox usage comes back on responses to a test key:

Header	Description
`X-Sandbox-Limit`	Sandbox requests included per month
`X-Sandbox-Used`	Sandbox requests used this month (org-wide)
`X-Sandbox-Remaining`	Sandbox requests left before the cap

Exhausting it returns 429 with code SANDBOX_QUOTA_EXCEEDED. Overage billing does not extend it — sandbox traffic is never billed, so there is nothing to invoice; the pool simply resets on the 1st. On the Sandbox plan there is no separate pool at all, because test requests are already what consume the 1,000. Quota state is returned on every authenticated response:

Header	Description
`X-Quota-Limit`	Requests included in your plan per month
`X-Quota-Used`	Billable requests used this month (org-wide)
`X-Quota-Remaining`	Billable requests left before the limit
`X-Quota-Billable`	Whether this request counted against the pool
`X-Quota-Overage`	Requests past the limit this month (only when over)
`X-Quota-Reset`	ISO timestamp when the pool resets

What happens at the limit depends on your overage billing setting (Dashboard → Billing):

Overage billing off (default): requests past the quota are rejected with 429 and code MONTHLY_QUOTA_EXCEEDED until the month resets. Your bill never exceeds your plan price.
Overage billing on (paid plans): traffic keeps flowing and extra requests are added to your next invoice at your plan’s overage rate ($0.003/request).

The Sandbox plan always hard-blocks — overage billing is a paid-plan setting, so a free organization can never be charged. And because overage is calculated from live traffic only, sandbox requests can never appear on an invoice on any plan.

{
  "error": "Quota exceeded",
  "message": "Monthly request quota reached (600,000 included requests). Enable overage billing or upgrade your plan at https://dashboard.clinikapi.com/billing to keep serving traffic.",
  "code": "MONTHLY_QUOTA_EXCEEDED"
}

PHI Sanitization

Error responses never contain Protected Health Information (PHI). Field values are stripped from validation error messages — only field names and constraint descriptions are included.

Getting Started

Guides

Legal

Errors

Errors

Error Response Format

HTTP Status Codes

Error Codes

Method Override Is Not Supported

SDK Error Handling

Automatic Retries

Rate Limits

Monthly Quotas & Overage

The sandbox pool

PHI Sanitization

​Errors

​Error Response Format

​HTTP Status Codes

​Error Codes

​Method Override Is Not Supported

​SDK Error Handling

​Automatic Retries

​Rate Limits

​Monthly Quotas & Overage

​The sandbox pool

​PHI Sanitization

Errors

Error Response Format

HTTP Status Codes

Error Codes

Method Override Is Not Supported

SDK Error Handling

Automatic Retries

Rate Limits

Monthly Quotas & Overage

The sandbox pool

PHI Sanitization