Erros¶

Esta página documenta todos os códigos de erro HTTP e os formatos de resposta de erro retornados pela API do Nodexa.

Formato de Resposta de Erro¶

Todos os erros retornam um corpo JSON com uma estrutura consistente:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Campo	Tipo	Descrição
`error.type`	`string`	Categoria do erro — confira a referência de tipos abaixo
`error.code`	`string`	Código de erro legível por máquina para tratamento programático
`error.message`	`string`	Descrição legível por humanos do erro

Códigos de Status HTTP¶

400 Bad Request¶

A request está malformada ou contém parâmetros inválidos.

`error.code`	Descrição
`invalid_request`	O corpo da request não é JSON válido
`missing_required_field`	Um campo obrigatório (`model`, `input`) está ausente
`invalid_model`	O campo `model` não é um UUID de assistant válido
`tool_not_supported_for_model`	O tipo de tool não é compatível com o modelo LLM de base
`too_many_tools`	Mais de 128 tools foram fornecidas
`duplicate_tool_name`	Duas ou mais tools na request têm o mesmo `name`
`invalid_tool_name`	Um nome de tool contém caracteres inválidos ou excede 64 caracteres
`invalid_input_type`	Um item no array `input` tem um `type` ou `role` não reconhecido
`missing_call_id`	Um item `function_call_output` está sem o campo `call_id`

Exemplo:

{
  "error": {
    "type": "invalid_request_error",
    "code": "too_many_tools",
    "message": "You provided 150 tools. The maximum is 128 per request."
  }
}

401 Unauthorized¶

Falha na autenticação. Nenhuma API key foi fornecida ou a chave não foi reconhecida.

`error.code`	Descrição
`missing_api_key`	Nenhum header `x-api-key` ou `Authorization` foi fornecido
`invalid_api_key`	A API key está malformada, expirou ou foi revogada

Exemplo:

{
  "error": {
    "type": "authentication_error",
    "code": "invalid_api_key",
    "message": "The provided API key is invalid or has been revoked."
  }
}

Checklist se você receber este erro:

Confira se sua API key começa com nxk_
Certifique-se de usar o header correto (x-api-key ou Authorization: Bearer)
Confira se a chave não foi revogada no painel administrativo
Confira se você está apontando para a URL correta da instância Nodexa

403 Forbidden¶

A API key é válida, mas não tem permissão para acessar este endpoint.

`error.code`	Descrição
`insufficient_scope`	O escopo da chave não inclui a permissão necessária

Exemplo:

{
  "error": {
    "type": "authentication_error",
    "code": "insufficient_scope",
    "message": "This API key requires the 'user' scope to access memory endpoints."
  }
}

Requisitos de escopo:

Endpoint	Escopo Necessário
`POST /v1/responses`	`assistant` ou `full_access`
`GET /user-claims/:userId`	`user` ou `full_access`
`POST /user-claims`	`user` ou `full_access`
`POST /user-claims/bulk`	`user` ou `full_access`
`DELETE /user-claims/:userId/:claimKey`	`user` ou `full_access`
`GET /v1/memory`	`user` ou `full_access`
`DELETE /v1/memory`	`user` ou `full_access`
`POST /v1/memory/opt-out`	`user` ou `full_access`

404 Not Found¶

O recurso solicitado não existe.

`error.code`	Descrição
`assistant_not_found`	Nenhum assistant existe com o UUID fornecido
`claim_not_found`	Nenhum claim existe para a combinação `userId` + `claimKey`
`memory_item_not_found`	Nenhum item de memória existe com o ID fornecido
`response_not_found`	O `previous_response_id` não corresponde a nenhuma resposta armazenada

Exemplo:

{
  "error": {
    "type": "not_found_error",
    "code": "assistant_not_found",
    "message": "No assistant found with ID 'asst_00000000-0000-0000-0000-000000000000'."
  }
}

422 Unprocessable Entity¶

A request é sintaticamente válida, mas falha na validação semântica.

`error.code`	Descrição
`claim_value_too_large`	O `claimValue` excede o limite de 64KB
`bulk_limit_exceeded`	Mais de 50 claims foram fornecidos em uma request bulk

503 Service Unavailable¶

A plataforma Nodexa ou uma dependência downstream está temporariamente indisponível.

`error.code`	Descrição
`upstream_unavailable`	O provedor LLM está inacessível ou retornou um erro de serviço
`upstream_timeout`	O provedor LLM não respondeu dentro do período de timeout
`service_overloaded`	A plataforma está sob alta carga; tente novamente após uma pausa

Exemplo:

{
  "error": {
    "type": "server_error",
    "code": "upstream_timeout",
    "message": "The LLM provider did not respond within the timeout period. Please try again."
  }
}

Retry com backoff exponencial

Para erros 503, implemente lógica de retry com backoff exponencial:

async function callWithRetry(fn, maxRetries = 3) {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err) {
      if (err.status === 503 && attempt < maxRetries - 1) {
        const delay = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise(r => setTimeout(r, delay));
        continue;
      }
      throw err;
    }
  }
}

Referência de Tipos de Erro¶

`error.type`	Significado
`authentication_error`	Falha de autenticação ou autorização
`invalid_request_error`	Parâmetros da request malformados ou inválidos
`not_found_error`	O recurso solicitado não existe
`validation_error`	Request é JSON válido, mas falha na validação semântica
`server_error`	Erro interno da plataforma ou falha do provedor upstream

Erros em Streaming¶

Quando stream: true, erros que ocorrem após o stream ter começado são entregues como eventos response.error em vez de códigos de status HTTP de erro (já que a resposta HTTP já começou com 200).

{
  "type": "response.error",
  "error": {
    "type": "server_error",
    "code": "upstream_timeout",
    "message": "The LLM provider did not respond within the timeout period."
  }
}

Após um evento response.error, o stream fecha. Sempre escute este evento no seu handler de stream:

for await (const event of stream) {
  if (event.type === 'response.error') {
    console.error('Stream error:', event.error.message);
    // Exibir estado de erro na interface
    break;
  }
  // ... tratar outros eventos
}

Boas Práticas de Tratamento de Erros¶

Confira o status antes de ler `output_text`¶

const response = await client.responses.create({ model, input });

if (response.status === 'requires_action') {
  // Tratar function calls — não leia output_text ainda
} else if (response.status === 'completed') {
  console.log(response.output_text);
}

Tratar 401 de forma centralizada¶

async function callNodexa(requestFn) {
  try {
    return await requestFn();
  } catch (err) {
    if (err.status === 401) {
      // API key inválida — registre com destaque, alerte o plantão
      console.error('CRITICAL: Nodexa API key invalid or revoked');
      throw err;
    }
    if (err.status === 503) {
      // Transitório — seguro para retentar
      throw err;
    }
    throw err;
  }
}

Validar resultados de function calls¶

// Sempre responda a function calls, mesmo em caso de erro
try {
  result = await myTool(args);
} catch (err) {
  result = { error: true, message: err.message };
}

toolResults.push({
  type: 'function_call_output',
  call_id: item.call_id,
  output: JSON.stringify(result), // sempre envie algo de volta
});

Erros¶

Formato de Resposta de Erro¶

Códigos de Status HTTP¶

400 Bad Request¶

401 Unauthorized¶

403 Forbidden¶

404 Not Found¶

422 Unprocessable Entity¶

503 Service Unavailable¶

Referência de Tipos de Erro¶

Erros em Streaming¶

Boas Práticas de Tratamento de Erros¶

Confira o status antes de ler output_text¶

Tratar 401 de forma centralizada¶

Validar resultados de function calls¶

Confira o status antes de ler `output_text`¶