Erros

A API da Valut foi projetada para retornar erros de forma clara, consistente e detalhada, permitindo fácil diagnóstico e tratamento programático.

Códigos de erro HTTP

Utilizamos códigos de status HTTP padrão para categorizar as respostas:

Código	Descrição
`200`	OK. A requisição foi processada com sucesso.
`400`	Bad Request. A requisição contém dados inválidos ou falhou por regras de negócio (ex: saldo insuficiente, validação).
`401`	Unauthorized. API Key inválida ou ausente.
`403`	Forbidden. Você não possui permissão para executar esta ação.
`404`	Not Found. O recurso solicitado não foi encontrado.
`408`	Request Timeout. Tempo limite da requisição excedido.
`429`	Too Many Requests. Limite de requisições excedido (rate limit).
`5xx`	Internal Error. Falha interna nos sistemas da Valut (raro).

⚠️ Erros 5xx são monitorados automaticamente pelo nosso sistema e tratados com prioridade.

Estrutura de erro

As respostas de erro seguem um formato padronizado:

{
  "type": "invalid_request_error",
  "code": "insufficient_funds",
  "message": "Saldo insuficiente para realizar a operação",
  "documentation_url": "https://docs.valutglobal.com/errors#insufficient_funds",
  "details": {
    "available_balance": 500,
    "required_amount": 1000
  }
}

Erros

Códigos de erro HTTP#

Estrutura de erro#

Códigos de erro HTTP

Estrutura de erro