Códigos de Erro

Todas as respostas de erro seguem o formato:

{
  "error": "Descrição legível do erro."
}

O campo error é sempre uma string em português.

Códigos HTTP

Erros do cliente (4xx)

Código	Nome	Descrição	Quando ocorre
400	Bad Request	Requisição inválida	Campos obrigatórios ausentes, formato inválido, imagem vazia
401	Unauthorized	Não autenticado	Chave de API ausente, inválida, expirada ou inativa
402	Payment Required	Créditos insuficientes	`POST /api/recognize` sem créditos disponíveis
403	Forbidden	Sem permissão	Chave válida mas sem scope para este recurso
404	Not Found	Recurso não encontrado	ID inexistente ou pertence a outro usuário
409	Conflict	Conflito	Câmera duplicada no agente, nome já existente
429	Too Many Requests	Rate limit excedido	Muitas requisições em pouco tempo

Erros do servidor (5xx)

Código	Nome	Descrição	Quando ocorre
500	Internal Server Error	Erro interno	Erro inesperado no servidor
502	Bad Gateway	Agente indisponível	Agente de processamento não respondeu
503	Service Unavailable	Serviço indisponível	Nenhum servidor de processamento disponível

Exemplos por cenário

Chave de API inválida

HTTP 401

{ "error": "Não autenticado." }

Câmera não encontrada

HTTP 404

{ "error": "Câmera não encontrada." }

Créditos insuficientes

HTTP 402

{ "error": "Créditos insuficientes. Adquira mais créditos para continuar." }

Agente de processamento offline

HTTP 502

{ "error": "Erro ao registrar câmera no agente de processamento." }

Imagem muito grande

HTTP 400

{ "error": "Imagem muito grande. Máximo 10MB." }

Rate limit

HTTP 429

{ "error": "Limite de requisições atingido. Aguarde um momento." }

Tratamento recomendado

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

  if (res.ok) {
    return await res.json();
  }

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

  switch (res.status) {
    case 401:
      // Chave inválida — verificar configuração
      throw new Error(`Auth error: ${error}`);
    case 402:
      // Sem créditos — comprar mais
      throw new Error(`Credits: ${error}`);
    case 429:
      // Rate limit — aguardar e tentar novamente
      await sleep(60000);
      return apiCall(url, options);
    case 502:
    case 503:
      // Servidor indisponível — retry com backoff
      await sleep(5000);
      return apiCall(url, options);
    default:
      throw new Error(`API error ${res.status}: ${error}`);
  }
}

Dica

Para erros 5xx, implemente retry com backoff exponencial: 1s, 2s, 4s, 8s, máximo 3 tentativas. Para erros 4xx, corrija a requisição antes de tentar novamente.