> ## Documentation Index
> Fetch the complete documentation index at: https://docs.crmspark.com.br/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript — erros e uso avançado

> Tratamento de erros, retentativas, timeouts, logging, fetch customizado e requisições além do catálogo tipado no sparkcrm.

O cliente [`sparkcrm`](https://www.npmjs.com/package/sparkcrm) inclui comportamentos de produção herdados do gerador [Stainless](https://www.stainless.com/). Esta página resume o que importa ao integrar o Spark de forma resiliente.

## Erros HTTP

Falhas de rede ou respostas `4xx` / `5xx` lançam subclasses de `SparkCRM.APIError`:

| Status            | Classe                      |
| ----------------- | --------------------------- |
| 400               | `BadRequestError`           |
| 401               | `AuthenticationError`       |
| 403               | `PermissionDeniedError`     |
| 404               | `NotFoundError`             |
| 422               | `UnprocessableEntityError`  |
| 429               | `RateLimitError`            |
| ≥ 500             | `InternalServerError`       |
| Sem resposta HTTP | `APIConnectionError`        |
| Timeout           | `APIConnectionTimeoutError` |

```ts theme={null}
import SparkCRM from "sparkcrm";

try {
  await client.entrypoints.list();
} catch (err) {
  if (err instanceof SparkCRM.RateLimitError) {
    // aguardar e tentar de novo, ou reduzir throughput
  } else if (err instanceof SparkCRM.APIError) {
    console.error(err.status, err.message);
  } else {
    throw err;
  }
}
```

Mensagens de validação da API (por exemplo variáveis de template faltando) costumam vir em `400` com texto descritivo no corpo.

## Retentativas

Por padrão o cliente **repete até 2 vezes** com backoff exponencial em:

* erros de conexão;
* `408`, `409`, `429`;
* `5xx`.

Desligar ou ajustar globalmente:

```ts theme={null}
const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY,
  maxRetries: 0,
});
```

Ou por requisição:

```ts theme={null}
await client.entrypoints.list({ maxRetries: 5 });
```

## Timeouts

Padrão: **60 segundos** por tentativa (com retentativas o tempo total pode ser maior).

```ts theme={null}
const client = new SparkCRM({
  timeout: 20_000,
});

await client.messaging.chats.sendMessage(chatId, { text: "ok" }, {
  timeout: 5_000,
});
```

## Resposta HTTP bruta

Métodos retornam `APIPromise<T>`. Para acessar cabeçalhos sem consumir o body:

```ts theme={null}
const response = await client.entrypoints.list().asResponse();
console.log(response.status, response.headers.get("x-request-id"));
```

Para dados parseados **e** `Response`:

```ts theme={null}
const { data, response } = await client.entrypoints.list().withResponse();
```

## Logging

Nível via `SPARK_CRM_LOG` ou `logLevel` no construtor: `debug`, `info`, `warn`, `error`, `off` (padrão `warn`).

Em `debug`, requisições e respostas são logadas (cuidado com dados sensíveis em produção).

Logger customizado (Pino, Winston, etc.):

```ts theme={null}
import SparkCRM from "sparkcrm";
import pino from "pino";

const client = new SparkCRM({
  apiKey: process.env.SPARK_API_KEY,
  logger: pino().child({ name: "spark" }),
  logLevel: "info",
});
```

## Fetch e proxy

Passe `fetch` alternativo ou `fetchOptions` (por exemplo `dispatcher` do Undici no Node para proxy corporativo). Exemplos no [README do repositório](https://github.com/gepetojj/spark-typescript/blob/main/README.md).

## Parâmetros e endpoints não documentados

O SDK não valida em runtime campos extras — você pode enviar opções ainda não refletidas nos tipos:

```ts theme={null}
await client.entrypoints.list({
  // @ts-expect-error parâmetro novo na API
  includeInactive: true,
});
```

Para rotas sem método dedicado:

```ts theme={null}
await client.post("/v1/messaging/chats/{chatId}/templates", {
  body: { templateId: "…", commonVariables: { var1: "x" } },
});
```

## Versionamento

O pacote segue [SemVer](https://semver.org/). Mudanças só de tipos podem sair em versão minor sem quebrar runtime. Acompanhe releases no [npm](https://www.npmjs.com/package/sparkcrm) e issues no [GitHub](https://github.com/gepetojj/spark-typescript/issues).

## Leitura relacionada

* [Começar com TypeScript](/sdks/typescript/introducao)
* [Referência de recursos](/sdks/typescript/referencia)
* [Introdução à API](/api-reference/introduction)