Errors and rate limits

HTTP status codes, problem-details bodies, and Partner API rate limits including Retry-After headers.

Most error bodies follow ASP.NET problem details (status, title, and often message). Always branch on the HTTP status, not on a free-text title.

Status codes

Status	When
200 / 201	Success. 201 is used when a resource is created (Location may be set).
400	Validation, future lastUpdated, insufficient wallet/subscription, or a business rule. Read message. Nothing is charged when a wallet check fails before create.
401	Missing, invalid, or inactive API client. Or the wrong regional host.
403	Authenticated, but the client is read-only (canWrite: false).
404	The key exists conceptually, but not in this practice.
429	Rate limit. Honour Retry-After.
500	Unexpected server error. Retry with backoff; contact support if it persists.

{
  "status": 401,
  "title": "Unauthorized"
}

Rate limits

Limits are per Client ID (defaults):

Window	Default
Minute	60
Hour	1,000
Day	10,000

On 429, response headers include:

Header	Meaning
Retry-After	Seconds to wait before retrying
X-RateLimit-Limit	Limit that was hit
X-RateLimit-Remaining	Remaining in the current window
X-RateLimit-Reset	When the window resets

Design for incremental sync and webhooks. Do not poll list endpoints every few seconds.

Wallet and subscription 400s

Routes that send eForms, KYC, AML, or onboardings may return 400 when the practice has no remaining subscription units or wallet balance. The API does not create the job or take a charge in that case. Ask the practice to top up, then retry.

Idempotency for webhooks

Inbound webhook deliveries include X-Om-Event-Id. Treat that as an idempotency key on your side so retries do not double-process. See Webhooks.