Erros

A API indica falhas pelo status HTTP. O corpo da resposta segue um destes formatos, então clientes com linguagem fortemente tipada devem estar preparados para desserializar todos eles.

Formatos

Erros de requisição (4xx com código)

Validações e regras de negócio retornam um código de topo e a lista de detalhes:

{
  "code": "resourceValidationErr",
  "errors": [
    {
      "code": null,
      "reason": "invalid value",
      "message": "must be a valid id",
      "property": "@.id"
    }
  ]
}

Campo	Tipo	Descrição
code	string	Código de topo (ver o catálogo abaixo)
errors	array	Detalhes de cada problema encontrado
errors[].code	string ou null	Código específico do detalhe
errors[].reason	string	Motivo do erro (ex.: invalid value, optional)
errors[].message	string	Mensagem legível
errors[].property	string	Caminho da propriedade que originou o erro (ex.: @.documentNumber; @ indica o identificador da URL)

Erros de autenticação (401 e 403)

{ "message": "Invalid API Key" }

Veja as mensagens possíveis em Autenticação.

Recurso não encontrado (404)

Quando o identificador é válido mas o recurso não existe, a API retorna 404 com corpo vazio.

Erro interno (500)

{
  "errorEventId": "a1b2c3d4e5f6",
  "message": "Internal server error."
}

Envie o errorEventId ao suporte para agilizar a investigação.

Limite de requisições (429)

Mais de 1 requisição por segundo retorna 429. Veja Limite de requisições.

Catálogo de códigos

resourceValidationErr

• Status: 422
• Quando acontece: o corpo da requisição tem campo obrigatório ausente, tipo errado ou valor fora das regras.
• Causas comuns: campo obrigatório não enviado (reason: optional); CPF/CNPJ inválido ou já cadastrado em outro cliente (reason: document number already exists); texto acima do tamanho máximo.
• Como resolver: confira o campo indicado em errors[].property contra a tabela de campos do endpoint.
• Endpoints de Clientes: criar e atualizar cliente, e-mail, telefone, localização; adicionar etiqueta; criar resposta de campo customizado.
• Endpoints de Colaboradores: criar colaborador (inclui e-mail já usado, reason: duplicated) e atualizar colaborador (inclui identificador inválido na URL, property: @.id).
• Endpoints de Materiais: criar e atualizar material (no atualizar, inclui identificador inválido na URL, property: @.id).
• Endpoints de Produtos: criar e atualizar produto (inclui code já usado e, no atualizar, produto inexistente com message: product/service not found).
• Endpoints de Tipos de produto: criar e atualizar tipo de produto (no atualizar, inclui tipo inexistente com message: products type not found).
• Endpoints de Produtos e serviços: criar e atualizar produto ou serviço (no atualizar, inclui registro inexistente com message: product/service not found).
• Endpoints de Tipos de OS: criar e atualizar tipo de OS (no atualizar, inclui identificador inválido na URL, property: @.id).
• Endpoints de Serviços: criar e atualizar serviço (no atualizar, inclui serviço inexistente com message: work service not found).
• Endpoints de Equipamentos: criar e atualizar equipamento (inclui number ou qrCode duplicados, tipo, cliente ou campo customizado não encontrados e, no atualizar, identificador inválido na URL com property: @.id).
• Endpoints de Tipos de equipamento: criar e atualizar tipo de equipamento (no atualizar, inclui identificador inválido na URL, property: @.id).
• Endpoints de Peças: criar e atualizar peça (campos obrigatórios, name ou code duplicados, tipo de peça inexistente, quantidade mínima negativa), arquivar peça já arquivada, desarquivar peça ativa, e adicionar ou remover tipo de equipamento.
• Endpoints de Tipos de peça: criar e atualizar tipo de peça (name ausente ou duplicado), arquivar tipo já arquivado e desarquivar tipo ativo.
• Endpoints de Unidades de peça: criar e atualizar unidade (campos obrigatórios, peça ou estoque inexistentes, campo de situação enviado) e ações com situação incompatível (reason: invalid status) ou estoque de triagem na liberação.
• Endpoints de Depósitos: criar e atualizar depósito (inclui nome já usado e, no atualizar, depósito inexistente com message: storage not found).
• Endpoints de Movimentações: efetuar movimentação e transferência por identificador externo (produto, depósito ou ordem inexistentes, saldo insuficiente, quantidade inválida).
• Endpoints de Veículos: criar e atualizar veículo (inclui marca ou modelo não encontrados pelo nome e, no atualizar, veículo inexistente com message: vehicle not found).
• Endpoints de Ordens de serviço: criar e atualizar ordem (inclui cliente, tipo de OS, localização, solicitação, contrato ou acordo não encontrados, número duplicado e, no atualizar, identificador inválido na URL); criar e atualizar atividade; anexar arquivo; comentar; vincular equipamento ou etiqueta; adicionar produto ou serviço; remover produto (v2); alterar respostas de formulário.
• Endpoints de Atividades: adicionar e remover colaborador secundário.
• Endpoints de Solicitações de serviço: criar e atualizar solicitação.
• Endpoints de Orçamentos: criar, atualizar, recusar e cancelar orçamento (inclui orçamento inexistente e situação que não permite a ação); adicionar etiqueta.
• Endpoints de Formulários respondidos: alterar respostas.
• Endpoints de Upload de arquivos: enviar arquivo.

parametersValidationErr

• Status: 422
• Quando acontece: um parâmetro de query é inválido.
• Causas comuns: limit fora de 1–100; offset fora de 0–200000; valor de sort não aceito; data inválida em um filtro (created_at>=:2026-02-31).
• Como resolver: veja Paginação e Filtros e ordenação.
• Endpoints de Clientes: todas as listagens.
• Endpoints de Colaboradores: listar colaboradores.
• Endpoints de Materiais: listar materiais.
• Endpoints de Produtos: listar produtos.
• Endpoints de Tipos de produto: listar tipos de produto.
• Endpoints de Produtos e serviços: listar produtos e serviços.
• Endpoints de Tipos de OS: listar tipos de OS.
• Endpoints de Serviços: listar serviços.
• Endpoints de Equipamentos: listar equipamentos.
• Endpoints de Tipos de equipamento: listar tipos de equipamento.
• Endpoints de Peças: listar peças.
• Endpoints de Tipos de peça: listar tipos de peça.
• Endpoints de Unidades de peça: listar unidades de peça.
• Endpoints de Depósitos: listar depósitos.
• Endpoints de Movimentações: listar movimentações e transferências.
• Endpoints de Veículos: listar veículos, marcas, modelos e usos.
• Endpoints de Ordens de serviço: listar ordens e atividades da ordem.
• Endpoints de Atividades: listar atividades e colaboradores secundários.
• Endpoints de Solicitações de serviço: listar solicitações.
• Endpoints de Orçamentos: listar orçamentos.
• Endpoints de Etiquetas, Avaliações, Acordos de atendimento e Contratos de prazos: listagens.

uriValidationErr

• Status: 422
• Quando acontece: o identificador na URL não é válido ou pertence a outra conta.
• Causas comuns: identificador digitado ou truncado; identificador de outro ambiente ou de outra conta.
• Como resolver: use o id exatamente como retornado pela API. Um identificador válido que não existe retorna 404, não este erro.
• Endpoints de Clientes: todos que recebem identificador na URL.
• Endpoints de Colaboradores: recuperar colaborador.
• Endpoints de Materiais: recuperar material.
• Endpoints de Produtos: recuperar e atualizar produto.
• Endpoints de Tipos de produto: recuperar e atualizar tipo de produto.
• Endpoints de Produtos e serviços: recuperar e atualizar produto ou serviço.
• Endpoints de Tipos de OS: recuperar tipo de OS e listar seus campos customizados.
• Endpoints de Serviços: recuperar e atualizar serviço.
• Endpoints de Equipamentos: recuperar equipamento.
• Endpoints de Tipos de equipamento: recuperar tipo de equipamento.
• Endpoints de Peças: recuperar, arquivar, desarquivar e adicionar ou remover tipo de equipamento.
• Endpoints de Tipos de peça: recuperar, arquivar e desarquivar tipo de peça.
• Endpoints de Unidades de peça: recuperar unidade e todas as ações.
• Endpoints de Depósitos: recuperar e atualizar depósito.
• Endpoints de Movimentações: recuperar movimentação.
• Endpoints de Veículos: recuperar e atualizar veículo, e recuperar uso de veículo.
• Endpoints de Ordens de serviço: todos que recebem o identificador da ordem ou do item na URL.
• Endpoints de Atividades: recuperar atividade e gerenciar colaboradores secundários.
• Endpoints de Solicitações de serviço: recuperar solicitação.
• Endpoints de Orçamentos: recuperar e atualizar orçamento; gerenciar etiquetas.
• Endpoints de Formulários respondidos: recuperar e alterar formulário.
• Endpoints de Etiquetas, Avaliações, Acordos de atendimento e Contratos de prazos: recuperar acordo ou contrato.

resourceAlreadyExists

• Status: 409
• Quando acontece: o recurso que você tenta criar ou vincular já existe.
• Causas comuns: adicionar ao cliente uma etiqueta que já está vinculada.
• Como resolver: consulte o recurso antes de criar, ou trate o 409 como sucesso quando o objetivo for garantir o vínculo.
• Endpoints de Clientes: adicionar etiqueta ao cliente.
• Endpoints de Tipos de equipamento: criar e atualizar tipo de equipamento com nome já usado na conta.
• Endpoints de Ordens de serviço: vincular equipamento, adicionar etiqueta e adicionar serviço já presentes na ordem.
• Endpoints de Orçamentos: adicionar etiqueta já presente no orçamento.

resourceNotAllowed

• Status: 422
• Quando acontece: a operação não é permitida para o recurso no estado atual.
• Como resolver: leia errors[].message para saber qual regra impediu a operação.
• Endpoints de Clientes: nenhum.
• Endpoints de Depósitos: todos, quando a conta não tem o módulo de controle de estoque (reason: storage control disabled).
• Endpoints de Movimentações: todos, quando a conta não tem o módulo de controle de estoque.

resourceNotFoundErr

• Status: 422
• Quando acontece: um recurso referenciado no corpo da requisição não foi encontrado (diferente do 404, que indica que o recurso da URL não existe).
• Como resolver: confira o identificador indicado em errors[].property.
• Endpoints de Clientes: nenhum.

resourceNotFound

• Status: 422
• Quando acontece: o recurso da URL não existe, em endpoints de peças, tipos de peça e unidades de peça (nesses endpoints não há 404).
• Causas comuns: identificador de um recurso apagado ou de outro ambiente.
• Como resolver: confira o identificador; liste os recursos para obter um id válido. Repare que o código não termina em Err, diferente de resourceNotFoundErr.

resourceLockedErr

• Status: 422
• Quando acontece: o recurso está bloqueado para alteração (ex.: ordem de serviço finalizada).
• Endpoints de Clientes: nenhum.
• Endpoints de Peças: atualizar, arquivar, desarquivar e adicionar ou remover tipo de equipamento de peça inexistente.
• Endpoints de Tipos de peça: atualizar, arquivar e desarquivar tipo de peça inexistente.
• Endpoints de Unidades de peça: instalar, desinstalar, descartar, devolver e liberar unidade inexistente.
• Endpoints de Ordens de serviço: alterar respostas de formulário de uma ordem travada.
• Endpoints de Formulários respondidos: alterar respostas de formulário de ordem travada.

cannotArchivePrimaryLocation

• Status: 422
• Quando acontece: tentativa de arquivar (archived: true) a localização primária de um cliente.
• Como resolver: defina outra localização como primária antes de arquivar esta.
• Endpoints de Clientes: atualizar localização do cliente.

cannotChangeCustomerOfPrimaryLocation

• Status: 422
• Quando acontece: tentativa de mover a localização primária para outro cliente.
• Como resolver: defina outra localização como primária no cliente atual antes de mover esta.
• Endpoints de Clientes: atualizar localização do cliente.

cannotSetArchivedLocationAsPrimary

• Status: 422
• Quando acontece: tentativa de definir como primária uma localização arquivada.
• Como resolver: desarquive a localização antes (archived: false).
• Endpoints de Clientes: atualizar localização primária.