Errors

Every LithosPOS API failure carries a stable machine-readable code alongside a human-readable message. Branch on code. Messages are translated server-side into the locale you send in Accept-Language and their wording changes without notice; codes do not.

Envelopes

The developer API and the partner API are different services and return different shapes.

Developer API — `/api/v2/developer/*`

{
  "error": {
    "code": "developer.grant_missing",
    "message": "This app is not authorised for merchant 104271.",
    "params": { "companyId": 104271 }
  }
}

Field	Type	Notes
`error.code`	string	Stable identifier. Always present
`error.message`	string	Localised, display-ready
`error.details`	object \| array	Field-level validation detail when applicable
`error.params`	object	Interpolation values used to build the message

Partner API — `/v1/*`

{
  "status": "error",
  "statusCode": 403,
  "timestamp": "2026-07-29T09:14:22.481Z",
  "path": "/v1/items",
  "message": "Your app does not have the items.write scope.",
  "code": "partner.scope_denied",
  "params": { "scope": "items.write" },
  "correlationId": "f2b1c8a4-9d13-4f77-8c0e-2a5b6e0d3417"
}

Field	Type	Notes
`status`	string	Always the literal `"error"`
`statusCode`	number	Mirrors the HTTP status
`timestamp`	string	ISO 8601, server clock
`path`	string	Request path
`message`	string	Localised. 5xx messages are deliberately generic
`code`	string	Present for all documented failures; absent for unclassified errors
`params`	object	Interpolation values
`correlationId`	string	UUID. Log it — support lookups start here

Developer API codes

Account and onboarding

Code	Status	Meaning
`developer.email_not_verified`	403	Sign-in attempted before the verification link was opened
`developer.too_many_attempts`	429	Repeated failed sign-ins — the account is locked for a short window
`developer.account_suspended`	403	The developer account is suspended; contact the program team
`developer.refresh_reuse_detected`	401	A refresh token was presented twice — the whole session family is revoked; sign in again
`developer.nda_required`	403	Account has not submitted a program application
`developer.nda_already_submitted`	409	A pending application already exists
`developer.nda_not_approved`	403	Program application is still pending or was declined
`developer.agreement_required`	403	Developer agreement not signed
`developer.agreement_version_stale`	409	Signature targets an agreement version that is no longer active — reload and sign the current one

Organizations and members

Code	Status	Meaning
`developer.not_org_member`	403	The account is not a member of that organization
`developer.insufficient_org_role`	403	Your role in the organization cannot perform this action
`developer.owner_immutable`	409	The organization owner cannot be removed or downgraded
`developer.invite_invalid`	400	The invitation link is malformed or was already used
`developer.invite_expired`	400	The invitation link expired — ask for a new invite

Apps, credentials and sandbox

Code	Status	Meaning
`developer.product_immutable`	409	An app’s product cannot change after creation
`developer.app_archived`	403	The app is archived; credentials no longer mint tokens
`developer.app_not_approved`	403	Production access attempted before review approval
`developer.review_not_in_review`	409	Review action attempted from the wrong state
`developer.sandbox_limit`	409	The organization already has three active sandbox merchants
`developer.sandbox_country_unknown`	400	The `country` code is not a supported ISO 3166-1 alpha-2 value

Token minting

Code	Status	Meaning
`developer.invalid_client`	401	Unknown client id, wrong secret or revoked credential — one code for all three, by design
`developer.merchant_required`	400	`merchant_id` omitted and not inferable
`developer.merchant_not_found`	404	`merchant_id` does not exist
`developer.merchant_inactive`	403	The merchant exists but is not active
`developer.grant_missing`	403	No active grant links this app to that merchant
`developer.env_mismatch`	403	Sandbox credential against a live merchant, or a production credential against a demo one
`developer.region_unconfigured`	503	The merchant’s region has no API base URL configured — contact support

These tables cover the codes an integration will realistically encounter; console-only flows (email verification, password reset, profile) carry additional developer.* codes that follow the same envelope.

Partner API codes

Code	Status	Meaning	Fix
`partner.scope_denied`	403	The route needs a scope your product bundle does not include	Use an app with the right product
`partner.env_mismatch`	403	Token environment does not match the merchant’s demo flag	Use the matching credential
`partner.ip_denied`	403	Source address is not on the credential’s allowlist	Update the allowlist, or call from the declared egress
`partner.grant_missing`	403	The grant was revoked after the token was minted	Re-mint; if it still fails, the merchant link is gone
`partner.rate_limited`	429	More than 300 requests in the current minute	Back off — see rate limits
`partner.window_too_large`	400	A report window exceeds 31 days	Split the range
`partner.invalid_window`	400	`from`/`to` is missing, malformed, or `to` precedes `from`	Send both as `YYYY-MM-DD`
`partner.order_not_found`	404	The online-order id does not exist in this merchant	Check the id returned at creation
`partner.acting_user_unavailable`	409	The merchant has no employee record to attribute writes to	Contact the merchant — their account is not fully set up

Platform codes

These come from the shared data layer and can surface on any partner route.

Code	Status	Meaning
`db.duplicate`	409	A unique constraint rejected the write — usually a repeated barcode, code or name
`db.not_found`	404	The referenced row does not exist in this merchant
`company.not_provisioned`	503	The merchant’s database is not ready yet. Retry shortly

Validation failures

Request bodies are validated strictly. Unknown properties are rejected, not ignored, so a typo in a field name fails loudly instead of silently dropping data.

{
  "status": "error",
  "statusCode": 400,
  "timestamp": "2026-07-29T09:20:03.117Z",
  "path": "/v1/items",
  "message": "groupId must be a number; property 'grupId' should not exist",
  "correlationId": "0b7a5c11-84c2-4f0a-9f2f-7c1e40d6b8aa"
}

Validation failures have no code — the message names the offending fields.

Retrying

Situation	Action
`429`	Wait until `X-RateLimit-Reset`, then retry. Do not retry immediately
`503 company.not_provisioned`	Retry with exponential backoff, up to about a minute
Other `5xx`	Retry up to three times with jittered backoff
`401` on a partner call	Mint a fresh token once, then retry. If it fails again, stop
Any other `4xx`	Do not retry — fix the request