Guia

Erros

Todos os erros da API do vokse devolvem um envelope JSON consistente, com um código estável legível por máquina, uma mensagem legível por pessoas e detalhes estruturados opcionais. Programe contra o código, mostre a mensagem.

O envelope de erro

As respostas que não são 2xx têm esta forma. O estado HTTP indica a classe; error.code diz exatamente o que aconteceu. details é um objeto opcional e traceId identifica o pedido nos nossos registos.

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 mais comuns

Estes são os códigos que mais provavelmente vai ter de tratar:

`INVALID_REQUEST`	422	O corpo ou os parâmetros de query do pedido não passaram na validação Zod. details.issues lista cada campo inválido.
`UNAUTHORIZED`	401	Cabeçalho Authorization em falta ou mal formado.
`SCOPE_DENIED`	403	A chave é válida, mas não tem o âmbito que este endpoint exige.
`API_KEY_NOT_ALLOWED`	403	Este endpoint é exclusivo de sessão e não pode ser chamado com uma chave de API.
`API_KEY_EXPIRED`	401	A chave passou a data de validade. Substitua-a.
`NOT_FOUND`	404	O recurso não existe ou não está visível para este agregado.
`IDEMPOTENCY_KEY_REUSED`	409	Uma Idempotency-Key foi reutilizada com um corpo de pedido diferente.
`RATE_LIMITED`	429	Demasiados pedidos. Abrande e tente de novo depois do tempo indicado no cabeçalho Retry-After.

Ler o campo details

No caso de INVALID_REQUEST, details.issues traz os problemas do Zod: uma entrada por campo inválido, com o caminho e a mensagem. Trate error.code como o contrato e error.message como texto para mostrar, que pode mudar; indique o traceId quando contactar o suporte.