Todas as rotas do Metrito possuem rate limiting para garantir estabilidade e uso justo da plataforma.
Limites por Tier
| Tier | Limite | Janela |
|---|
| API Key padrão | 120 req | 1 minuto |
| Growth | 300 req | 1 minuto |
| Enterprise | 1.000 req | 1 minuto |
/v3/ inclui headers de rate limit:
| Header | Descrição |
|---|
X-RateLimit-Limit | Limite máximo de requisições na janela |
X-RateLimit-Remaining | Requisições restantes na janela atual |
X-RateLimit-Reset | Timestamp Unix de quando a janela reseta |
Retry-After | Segundos até poder tentar novamente (apenas em 429) |
429 Too Many Requests:
{
"error": {
"type": "rate_limit_error",
"code": "rate_limit_exceeded",
"message": "Rate limit exceeded. Maximum 120 requests per 60s.",
"request_id": "req_abc123"
}
}
- Respeite o header
Retry-After antes de tentar novamente
- Implemente backoff exponencial para retries
- Agrupe múltiplas consultas em uma única chamada quando possível (ex: multiple fields em
POST /v3/query)
- Cache respostas que não mudam frequentemente (
GET /v3/fields)
Request ID
Toda resposta inclui o header X-Request-Id. Use este ID ao entrar em contato com o suporte.
X-Request-Id: req_k8mN2pQ4rT6wX1
Idempotência
Endpoints de escrita (POST /v3/tracking/events, POST /v3/tracking/containers/:id/events) suportam o header Idempotency-Key.
curl -X POST https://api.metrito.com/v3/tracking/events \
-H "Authorization: Bearer mtk_live_abc123..." \
-H "Idempotency-Key: meu-evento-unico-123" \
-H "Content-Type: application/json" \
-d '{ "config": { "name": "Purchase" } }'
| Comportamento | Descrição |
|---|
| Primeira chamada | Processa normalmente e armazena resultado |
| Chamada repetida (mesmo key, 24h) | Retorna resultado armazenado com header X-Idempotent-Replayed: true |
| Após 24h | Key expira, chamada é processada novamente |
O Idempotency-Key é vinculado à API key. Chaves diferentes podem usar o mesmo valor sem conflito.
Todas as rotas /v3/ retornam erros no formato:
{
"error": {
"type": "authentication_error",
"code": "invalid_api_key",
"message": "The API key provided is invalid or has been revoked.",
"request_id": "req_abc123"
}
}
Tipos de Erro
| Tipo | HTTP Status | Descrição |
|---|
authentication_error | 401 | Credencial ausente, inválida ou expirada |
authorization_error | 403 | Permissão insuficiente (escopo) |
validation_error | 400 | Parâmetro ausente ou inválido |
not_found_error | 404 | Recurso não encontrado |
rate_limit_error | 429 | Limite de requisições excedido |
api_error | 500 | Erro interno do servidor |
Códigos de Erro
| Código | Descrição |
|---|
invalid_api_key | API key inválida ou revogada |
expired_api_key | API key expirada |
insufficient_scope | API key não possui o escopo necessário |
rate_limit_exceeded | Limite de requisições excedido |
invalid_parameter | Parâmetro de request inválido |
missing_parameter | Parâmetro obrigatório ausente |
resource_not_found | Recurso não encontrado |
idempotency_conflict | Conflito de idempotência |
internal_error | Erro interno |
