Errors

Every error is one JSON envelope. Branch on code; show message to a developer, never to a member.

json

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_secret_key",
    "message": "Invalid secret key.",
    "param": "..."          // present when one field is at fault
  }
}

Codes you will actually see

Status	Code	Do
401	`invalid_secret_key`	The key is missing, malformed, or unknown. Check which credential your server sends.
401	`publishable_key_used`	You sent pk where sk belongs. Sessions are minted server-side with the secret key.
403	`key_revoked`	Rotated past grace, or revoked. Deploy the replacement key.
403	`account_suspended`	Your company's access is off. Contact support.
400	`missing_host_user_ref`	Sessions require your member ID — it is the billing unit.
429	`rate_limit_exceeded`	Back off and retry. Applies to auth endpoints.
429	`quota_exceeded`	The app's daily session ceiling. Contact support if legitimate traffic hit it.

SDK-side failures

The SDK surfaces failures as ScanError values with a readable description — network, session invalid, capture abandoned (the member changed their mind; not an error to alarm on), or a named processing step. A scan that completed offline still returns its result; only the usage report waits for connectivity.