Error registry

Errors arrive in the envelope's Errors list as stable string codes. Branch on the Code, never on the human-readable Message. This page lists the codes every integration should handle; domain-specific codes (prefixed by their area, e.g. PAYMENT_TERMINAL_…, API_KEY_…) are documented with their endpoints in the reference.

Authentication and authorization

HTTP	Code	Meaning	Do
401	—	Missing, unknown or revoked credential	Fix the credential; don't retry
403	API_KEY_SCOPE_INSUFFICIENT	The key lacks the scope the endpoint requires (named in the message)	Ask your admin to grant it
403	PUBLIC_API_LICENSE_INACTIVE	Your organisation's API license lapsed	Alert your admin; back off, don't loop
403	ACCESS_IS_FORBIDDEN	The record exists but belongs outside your scope	Treat like 404

Requests

HTTP	Code pattern	Meaning	Do
400	area-specific …_MANDATORY / …_ERROR codes	Validation failed; the message says which field	Fix the request
400	filterable-property error	A dsquery field name isn't filterable/sortable (the property is named)	Fix the field name
404	NOT_FOUND and area-specific …_NOT_FOUND	No such record in your scope	Handle as absent
422	request-shape codes	The body was structurally unusable	Fix the request

Platform

HTTP	Meaning	Do
429	You hit your subscription's rate limit at the gateway	Honor Retry-After, add backoff
500	Platform fault — the response still carries the envelope	Retry with backoff; report with your X-Correlation-Id if persistent

A worked failure

{
  "Result": false,
  "Errors": [
    {
      "Code": "API_KEY_SCOPE_INSUFFICIENT",
      "Category": 4,
      "Message": "This endpoint requires the 'tariffs:readwrite' scope"
    }
  ]
}

Category is a coarse machine grouping (bad data, not found, forbidden, server error); the Code is the contract.