Errors

All errors are returned in the standard envelope:

{
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Partner not found",
    "details": { "uuid": "…" },
    "requestId": "req_01H…"
  }
}

HTTP status mapping

Status	Meaning
`400`	Validation or business-rule failure (see `code`)
`401`	Missing/invalid credentials
`403`	Authenticated but not allowed for this resource (RBAC)
`404`	Resource does not exist or is not visible to you
`409`	Conflict (duplicate, concurrent modification)
`422`	Semantically invalid request (e.g. wrong state machine)
`429`	Rate limit exceeded — see Rate limits
`5xx`	Server-side error — safe to retry idempotent operations

Code catalogue (excerpt)

Nova ships a stable code list — only additions are made between minor
versions. Removed or renamed codes are announced in the
Changelog at least 90 days in advance.

Code	Typical status	Meaning
`VALIDATION_FAILED`	400	Request body failed schema validation
`BUSINESS_RULE_VIOLATION`	400	Request was schema-valid but rejected by a rule
`UNAUTHORIZED`	401	Credential missing or invalid
`TOKEN_EXPIRED`	401	JWT expired — refresh and retry
`FORBIDDEN`	403	Caller lacks permission
`RESOURCE_NOT_FOUND`	404	Resource does not exist or is not visible
`DUPLICATE_RESOURCE`	409	Unique constraint violated
`CONCURRENT_MODIFICATION`	409	Optimistic-lock conflict, refetch and retry
`INVALID_STATE_TRANSITION`	422	Requested transition not allowed from current state
`RATE_LIMITED`	429	Quota exceeded
`UPSTREAM_PROVIDER_ERROR`	502/504	A third-party (Nexus, payment, KYC) call failed
`INTERNAL_ERROR`	500	Unexpected — quote the `requestId` to support

Handling guidance

Always read error.code. Never branch on error.message text.
For 5xx and UPSTREAM_PROVIDER_ERROR, retry idempotent calls with
exponential backoff (start 500 ms, cap at 30 s, ≤ 5 attempts).
For 429, honour the Retry-After header if present.
For CONCURRENT_MODIFICATION, refetch the resource before retrying.
Log requestId on every failure — it is the fastest way for support to
pull the matching server log.