Guía

Errores

Cada error de la API de vokse devuelve siempre el mismo envoltorio JSON con un código estable legible por máquina, un mensaje para humanos y, opcionalmente, detalles estructurados. Programa según el código y muestra el mensaje.

El envoltorio de error

Las respuestas que no son 2xx llevan esta forma. El estado HTTP te indica la clase; error.code te dice exactamente qué ocurrió. details es un objeto opcional y traceId identifica la petición en nuestros 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"  }}

Códigos habituales

Estos son los códigos que con más probabilidad tendrás que gestionar:

`INVALID_REQUEST`	422	El cuerpo o la query de la petición no ha pasado la validación de Zod. details.issues enumera cada campo problemático.
`UNAUTHORIZED`	401	Falta la cabecera Authorization o está mal formada.
`SCOPE_DENIED`	403	La clave es válida pero le falta el scope que este endpoint requiere.
`API_KEY_NOT_ALLOWED`	403	Este endpoint es solo de sesión y no puede llamarse con una clave de API.
`API_KEY_EXPIRED`	401	La clave ha superado su fecha de caducidad. Rótala.
`NOT_FOUND`	404	El recurso no existe o no es visible para este hogar.
`IDEMPOTENCY_KEY_REUSED`	409	Se ha reutilizado una Idempotency-Key con un cuerpo de petición distinto.
`RATE_LIMITED`	429	Demasiadas peticiones. Reduce el ritmo y reintenta pasados los segundos que indica la cabecera Retry-After.

Leer los detalles

En INVALID_REQUEST, details.issues contiene los issues de Zod: una entrada por campo inválido con su ruta y su mensaje. Trata error.code como el contrato y error.message como texto para mostrar, que puede cambiar; incluye el traceId cuando escribas a soporte.