Guide

Errors

Every error from the vokse API returns a consistent JSON envelope with a stable machine-readable code, a human message, and optional structured details. Build against the code, surface the message.

The error envelope

Non-2xx responses carry this shape. The HTTP status tells you the class; error.code tells you exactly what happened. details is an optional object, and traceId identifies the request in our logs.

json

{  "error": {    "code": "SCOPE_DENIED",    "message": "API key is missing required scopes: write:transactions",    "details": {      "requiredScopes": ["write:transactions"],      "grantedScopes": ["read:transactions"],      "missing": ["write:transactions"]    },    "traceId": "01J8MEB4W2Q0F7GXK3N5D8C1VZ"  }}

Common codes

These are the codes you are most likely to handle:

`INVALID_REQUEST`	422	The request body or query failed Zod validation. details.issues lists each offending field.
`UNAUTHORIZED`	401	Missing or malformed Authorization header.
`SCOPE_DENIED`	403	The key is valid but lacks the scope this endpoint requires.
`API_KEY_NOT_ALLOWED`	403	This endpoint is session-only and cannot be called with an API key.
`API_KEY_EXPIRED`	401	The key passed its expiry date. Rotate it.
`NOT_FOUND`	404	The resource does not exist or is not visible to this household.
`IDEMPOTENCY_KEY_REUSED`	409	An Idempotency-Key was reused with a different request body.
`RATE_LIMITED`	429	Too many requests. Back off and retry after the Retry-After header.

Reading details

For INVALID_REQUEST, details.issues carries the Zod issues: one entry per invalid field with its path and message. Treat error.code as the contract and error.message as display copy that may change; quote traceId when you contact support.