Limitação de taxa

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

Configuração de 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 minuto	60 solicitações/minuto
Por hora	1.000 solicitações/hora
Por dia	10.000 solicitações/dia

Cada configuração de limite de taxa contém uma única janela e máximo — uma chave não pode combinar múltiplas janelas (por exemplo, um limite por minuto e por hora na mesma chave não é compatível). Os limites se acumulam apenas entre níveis: um limite de taxa no nível da organização (definido por meio de PATCH /api/v1/authentication/orgs/{orgId}/rate-limit) e um limite no nível da chave podem ser aplicados à mesma solicitação.

Demonstração: limitação de taxa em ação

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

Solicitação 1 — bem-sucedida

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": "Olá, como você está?",
    "stream": false
  }'

Resposta: HTTP 200

{
  "id": "resp_5ab19d58984940c88a971c6829ae201c",
  "object": "response",
  "status": "completed",
  "model": "meetkai:functionary-pt",
  "output": [
    {
      "type": "message",
      "role": "assistant",
      "content": [{ "type": "output_text", "text": "Olá! Estou bem..." }]
    }
  ]
}

Solicitação 2 — limitada por taxa (enviada imediatamente depois)

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": "Isto deve ser limitado por taxa",
    "stream": false
  }'

Resposta: HTTP 429

{
  "error": "Rate limit exceeded"
}

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

Exemplo programático

# Primeira solicitação — bem-sucedida (HTTP 200)
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Olá"' \
  --include-headers \
  -H 'X-On-Behalf-Of: <end-user-id>'

# Segunda solicitação — limitada por taxa (HTTP 429)
mka1 llm responses create \
  --model meetkai:functionary-pt \
  --input '"Isto será limitado por taxa"' \
  --include-headers \
  -H 'X-On-Behalf-Of: <end-user-id>'

import OpenAI from 'openai';

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

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

// Segunda solicitação — limitada por taxa
try {
  await openai.responses.create({
    model: 'meetkai:functionary-pt',
    input: 'Isto será limitado por taxa',
    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" }
  }
}

import { SDK } from '@meetkai/mka1';
import { APIError } from '@meetkai/mka1/models/errors';
import type { ResponseObject } from '@meetkai/mka1/models/components';

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

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

// Segunda solicitação — limitada por taxa
try {
  await mka1.llm.responses.create({
    responsesCreateRequest: {
      model: 'meetkai:functionary-pt',
      input: 'Isto será limitado por taxa',
    },
  });
} catch (err) {
  if (err instanceof APIError && err.statusCode === 429) {
    console.log(err.statusCode); // 429
    console.log(err.body);       // '{"error":"Rate limit exceeded"}'
  }
}

using MeetKai.MKA1;
using MeetKai.MKA1.Types.Components;
using MeetKai.MKA1.Types.Errors;

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

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

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

import time
from meetkai_mka1 import SDK
from meetkai_mka1.errors import SDKDefaultError

sdk = SDK(bearer_auth="Bearer YOUR_API_KEY")

try:
    res = sdk.llm.responses.create(
        model="meetkai:functionary-pt",
        input="Resuma este documento.",
    )
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="Resuma este documento.",
        )
    else:
        raise

# Primeira solicitaçã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": "Olá", "stream": false }'

# Segunda solicitaçã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": "Isto será limitado por taxa", "stream": false }'

A resposta 429

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

Campo	Valor
Status HTTP	`429 Too Many Requests`
Content-Type	`application/json`
Corpo	`{"error": "Rate limit exceeded"}`
Tokens consumidos	0 — a solicitaçã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.

Como lidar com limites de taxa na sua aplicação

Quando sua aplicação recebe uma resposta 429, tente novamente com recuo exponencial:

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: 'Olá', stream: false })
);

Veja também

Autenticação para configuração da chave de API e o padrão X-On-Behalf-Of.
Autorização para controle de acesso no nível de recurso.
Gerar uma resposta para o formato básico da solicitação Responses.

Primeiros passos

Respostas

Recursos

Computação

CLI

Receitas

Benchmarks

Infraestrutura

Limitação de taxa

Configuração de limite de taxa

Demonstração: limitação de taxa em ação

Solicitação 1 — bem-sucedida

Solicitação 2 — limitada por taxa (enviada imediatamente depois)

Exemplo programático

A resposta 429

Como lidar com limites de taxa na sua aplicação

Veja também

​Configuração de limite de taxa

​Demonstração: limitação de taxa em ação

​Solicitação 1 — bem-sucedida

​Solicitação 2 — limitada por taxa (enviada imediatamente depois)

​Exemplo programático

​A resposta 429

​Como lidar com limites de taxa na sua aplicação

​Veja também

Configuração de limite de taxa

Demonstração: limitação de taxa em ação

Solicitação 1 — bem-sucedida

Solicitação 2 — limitada por taxa (enviada imediatamente depois)

Exemplo programático

A resposta 429

Como lidar com limites de taxa na sua aplicação

Veja também