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

# Limite de Taxa

> Limites de taxa por chave com cotas configuráveis por segundo, minuto, hora ou dia. Inclui demonstração real de HTTP 429 e padrões de retentativa.

A API MKA1 aplica limites de taxa em uma **base por chave**.
Cada chave de API tem sua própria cota configurada independentemente — requisições por segundo, minuto, hora ou dia.
Quando uma chave excede seu limite, o gateway retorna `429 Too Many Requests` antes que a requisição chegue ao modelo. Nenhum token é consumido e nenhum uso é cobrado.

## Configuração do limite de taxa

Os limites de taxa são definidos por chave de API no momento do provisionamento. As granularidades disponíveis são:

| Janela      | Exemplo                |
| ----------- | ---------------------- |
| Por segundo | 10 requisições/segundo |
| Por minuto  | 60 requisições/minuto  |
| Por hora    | 1.000 requisições/hora |
| Por dia     | 10.000 requisições/dia |

Os limites podem ser combinados — por exemplo, 10 requisições/segundo **e** 5.000 requisições/hora na mesma chave.

## Demonstração: limite de taxa em ação

O exemplo a seguir usa uma chave de API real configurada com um limite de taxa de **1 requisição por minuto**. A primeira requisição é bem-sucedida, e a segunda requisição — enviada imediatamente após — é rejeitada com HTTP 429.

### Requisição 1 — bem-sucedida

```bash theme={null}
curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer mk-YfcgFr...BsFLzg' \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "Hello, how are you?",
    "stream": false
  }'
```

**Resposta: HTTP 200**

```json theme={null}
{
  "id": "resp_5ab19d58984940c88a971c6829ae201c",
  "object": "response",
  "status": "completed",
  "model": "meetkai:functionary-pt",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Hello! I'm doing well..." }]
    }
  ]
}
```

### Requisição 2 — limitada por taxa (enviada imediatamente após)

```bash theme={null}
curl https://apigw.mka1.com/api/v1/llm/responses \
  --request POST \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer mk-YfcgFr...BsFLzg' \
  --data '{
    "model": "meetkai:functionary-pt",
    "input": "This should be rate limited",
    "stream": false
  }'
```

**Resposta: HTTP 429**

```json theme={null}
{
  "error": "Rate limit exceeded"
}
```

O gateway rejeita a requisição antes que ela chegue ao modelo — nenhum token é consumido e nenhum uso é cobrado.

### Exemplo programático

<CodeGroup>
  ```bash CLI theme={null}
  # Primeira requisição — bem-sucedida (HTTP 200)
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --input '"Hello"' \
    --include-headers \
    -H 'X-On-Behalf-Of: <end-user-id>'

  # Segunda requisição — limitada por taxa (HTTP 429)
  mka1 llm responses create \
    --model meetkai:functionary-pt \
    --input '"This will be rate limited"' \
    --include-headers \
    -H 'X-On-Behalf-Of: <end-user-id>'
  ```

  ```ts OpenAI SDK theme={null}
  import OpenAI from 'openai';

  const openai = new OpenAI({
    apiKey: '<mka1-api-key>',
    baseURL: 'https://apigw.mka1.com/api/v1/llm/',
  });

  // Primeira requisição — bem-sucedida
  const response = await openai.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Hello',
    stream: false,
  });
  console.log(response.status); // "completed"

  // Segunda requisição — limitada por taxa
  try {
    await openai.responses.create({
      model: 'meetkai:functionary-pt',
      input: 'This will be rate limited',
      stream: false,
    });
  } catch (err) {
    if (err instanceof OpenAI.RateLimitError) {
      console.log(err.status);   // 429
      console.log(err.message);  // "429 Rate limit exceeded"
      console.log(err.error);    // { error: "Rate limit exceeded" }
    }
  }
  ```

  ```ts MKA1 SDK theme={null}
  import { SDK } from '@meetkai/mka1';
  import { APIError } from '@meetkai/mka1/models/errors';

  const mka1 = new SDK({
    bearerAuth: `Bearer <mka1-api-key>`,
  });

  // Primeira requisição — bem-sucedida
  const response = await mka1.llm.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Hello',
  });
  console.log(response.status); // "completed"

  // Segunda requisição — limitada por taxa
  try {
    await mka1.llm.responses.create({
      model: 'meetkai:functionary-pt',
      input: 'This will be rate limited',
    });
  } catch (err) {
    if (err instanceof APIError && err.statusCode === 429) {
      console.log(err.statusCode); // 429
      console.log(err.body);       // '{"error":"Rate limit exceeded"}'
    }
  }
  ```

  ```csharp C# SDK theme={null}
  using MeetKai.MKA1;
  using MeetKai.MKA1.Types.Components;
  using MeetKai.MKA1.Types.Errors;

  var sdk = new SDK(bearerAuth: "Bearer YOUR_API_KEY");

  // Primeira requisição — bem-sucedida
  var response = await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
  {
      Model = "meetkai:functionary-pt",
      Input = ResponsesCreateRequestInput.CreateStr("Hello"),
  });

  // Segunda requisição — pode ser limitada por taxa
  try
  {
      await sdk.Llm.Responses.CreateAsync(new ResponsesCreateRequest()
      {
          Model = "meetkai:functionary-pt",
          Input = ResponsesCreateRequestInput.CreateStr("This will be rate limited"),
      });
  }
  catch (APIException ex) when ((int)ex.Response.StatusCode == 429)
  {
      Console.WriteLine(ex.Response.StatusCode); // TooManyRequests
      Console.WriteLine(ex.Body);               // "Rate limit exceeded"
  }
  ```

  ```python Python SDK theme={null}
  import time
  from mka1 import SDK
  from mka1.errors import SDKDefaultError

  sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

  try:
      res = sdk.llm.responses.create(
          model="meetkai:functionary-pt",
          input="Summarize this document.",
      )
  except SDKDefaultError as e:
      if e.status_code == 429:
          time.sleep(int(e.headers.get("retry-after", 1)))
          res = sdk.llm.responses.create(
              model="meetkai:functionary-pt",
              input="Summarize this document.",
          )
      else:
          raise
  ```

  ```bash bash theme={null}
  # Primeira requisição — bem-sucedida (HTTP 200)
  curl -s -w "\nHTTP %{http_code}" https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --data '{ "model": "meetkai:functionary-pt", "input": "Hello", "stream": false }'

  # Segunda requisição — limitada por taxa (HTTP 429)
  curl -s -w "\nHTTP %{http_code}" https://apigw.mka1.com/api/v1/llm/responses \
    --request POST \
    --header 'Content-Type: application/json' \
    --header 'Authorization: Bearer <mka1-api-key>' \
    --data '{ "model": "meetkai:functionary-pt", "input": "This will be rate limited", "stream": false }'
  ```
</CodeGroup>

## A resposta 429

Quando uma requisição é limitada por taxa, o gateway retorna:

| Campo                 | Valor                                  |
| --------------------- | -------------------------------------- |
| **HTTP status**       | `429 Too Many Requests`                |
| **Content-Type**      | `application/json`                     |
| **Corpo**             | `{"error": "Rate limit exceeded"}`     |
| **Tokens consumidos** | 0 — a requisição nunca chega ao modelo |
| **Uso cobrado**       | Nenhum                                 |

O SDK OpenAI apresenta isso como um `OpenAI.RateLimitError` com `err.status === 429`.
O SDK MKA1 lança um `APIError` com `err.statusCode === 429`.

## Lidando com limites de taxa em sua aplicação

Quando sua aplicação receber uma resposta 429, faça retentativas com backoff exponencial:

```ts theme={null}
async function requestWithRetry(fn: () => Promise<any>, maxRetries = 3): Promise<any> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await fn();
    } catch (err: any) {
      if (err.status === 429 && attempt < maxRetries - 1) {
        const waitMs = Math.pow(2, attempt) * 1000; // 1s, 2s, 4s
        await new Promise((r) => setTimeout(r, waitMs));
        continue;
      }
      throw err;
    }
  }
}

const response = await requestWithRetry(() =>
  openai.responses.create({ model: 'meetkai:functionary-pt', input: 'Hello', stream: false })
);
```

## Veja também

* [Autenticação](/pt/docs/authentication) para configuração de chave de API e o padrão `X-On-Behalf-Of`.
* [Autorização](/pt/docs/authorization) para controle de acesso a nível de recurso.
* [Gerar uma resposta](/pt/docs/generate-a-response) para o formato básico da requisição de respostas.