Saltar para o conteúdo principal

Documentation Index

Fetch the complete documentation index at: https://developers.vendaze.com/llms.txt

Use this file to discover all available pages before exploring further.

A Vendaze API usa códigos de status HTTP padrão e retorna um formato de erro consistente em toda falha.

​
Formato do erro

{
  "error": {
    "code": "not_found",
    "message": "Person not found.",
    "request_id": "550e8400-e29b-41d4-a716-446655440000"
  }
}
CampoDescrição
codeCódigo de erro legível por máquina. Use em lógica de tratamento.
messageDescrição em inglês para desenvolvedores. Não exiba ao usuário final.
request_idID único da requisição. Inclua ao contatar o suporte.
Uma resposta com status 2xx nunca contém error. Uma resposta com status não-2xx sempre contém error.

​
Códigos de status HTTP

StatusSignificado
200Sucesso. Recurso lido ou atualizado.
201Criado com sucesso.
204Sem conteúdo. Recurso deletado. Body vazio.
400Requisição malformada ou parâmetro obrigatório ausente.
401Não autenticado. Token ausente, inválido ou expirado.
403Sem permissão. Token válido mas escopo insuficiente.
404Não encontrado. Recurso não existe, foi deletado, ou pertence a outro workspace.
422Validação falhou. Veja o objeto fields.
429Limite de taxa excedido.
500Erro interno. Algo deu errado no servidor.

​
Referência de códigos de erro

CódigoHTTPQuando ocorre
unauthorized401Token Bearer ausente ou assinatura inválida.
token_expired401Access token expirado. Renove usando o refresh token.
insufficient_scope403Token sem o escopo necessário para este endpoint.
forbidden403Autenticado, mas sem permissão para este recurso.
not_found404Recurso inexistente, deletado, ou de outro workspace.
validation_error422Input falhou na validação. Veja fields para detalhes.
rate_limit_exceeded429Muitas requisições. Aguarde o tempo indicado em Retry-After.
internal_error500Erro inesperado. Use o request_id ao contatar suporte.

​
Erros de validação

Quando a validação falha, a resposta inclui o objeto fields mapeando cada campo ao problema: 
{
  "error": {
    "code": "validation_error",
    "message": "Validation failed.",
    "fields": {
      "per_page": "Must be at most 100.",
      "due_date": "Invalid ISO 8601 date format."
    },
    "request_id": "uuid"
  }
}

​
Tratamento em código

async function apiCall(url, options) {
  const res = await fetch(url, options);

  if (!res.ok) {
    const { error } = await res.json();

    switch (error.code) {
      case 'token_expired':
        await refreshAccessToken();
        return apiCall(url, options);

      case 'rate_limit_exceeded': {
        const retryAfter = parseInt(res.headers.get('Retry-After') ?? '60');
        await new Promise((r) => setTimeout(r, retryAfter * 1000));
        return apiCall(url, options);
      }

      case 'not_found':
        return null;

      default:
        throw new Error(`${error.code}: ${error.message} (request_id: ${error.request_id})`);
    }
  }

  return res.json();
}