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

# Uso y límites

> Cómo mide Retailgrid el uso de la API y de MCP por organización, qué ocurre cuando se agota el presupuesto y cómo aplicar un backoff.

Retailgrid mide el uso para que un solo pipeline, o un bucle descontrolado, no pueda agotar los recursos que sostienen a todos los demás. Las lecturas, escrituras, exportaciones y sondeos cuentan por igual, tanto en la [API pública](https://docs.retailgrid.io/es/api-reference/introduction.md) como en el [conector MCP](https://docs.retailgrid.io/es/settings/ai-connections.md).

## Qué se mide y con qué granularidad

El uso se contabiliza **por organización**. El presupuesto se comparte entre todas las claves de API, todos los usuarios y el conector MCP, así que repartir las llamadas entre más claves o más endpoints no eleva tu techo: todo consume del mismo presupuesto de la organización.

El uso se registra en varias **dimensiones**, cada una con su propia `unit`:

| Unidad | Qué cuenta |
| :- | :- |
| `requests` | Solicitudes individuales a la API. |
| `calls` | Llamadas a herramientas MCP. |
| `active_work` | Trabajo concurrente en curso (operaciones largas y trabajos). |
| `bytes` | Volumen de datos movido por una operación, por ejemplo una exportación grande. |

## Cuando se agota el presupuesto

Un presupuesto agotado se rechaza **antes** de cualquier procesamiento costoso, así que no se te factura por trabajo que nunca se ejecutó. La respuesta es `429 Too Many Requests` con:

* un encabezado `Retry-After`, y
* un cuerpo JSON cuyo `detail` indica exactamente qué límite se alcanzó y cuándo se libera.

```json theme={null}
{
  "detail": {
    "code": "organization_usage_limit_exceeded",
    "dimension": "transactions_read",
    "unit": "requests",
    "limit": 100000,
    "remaining": 0,
    "request_id": "0b3c1f4a-9c1d-4f2a-8a3b-2c3d4e5f6a7b",
    "reset_at": "2026-10-08T00:00:00Z",
    "retry_after": 3600
  }
}
```

`reset_at` indica cuándo se recarga el presupuesto; `retry_after` es la misma espera en segundos y refleja el encabezado `Retry-After`. Como el presupuesto es compartido, cambiar a otra clave de API **no** restaura el acceso: espera al reinicio.

## Cómo comportarse bien

* **Respeta `Retry-After`.** Espera el intervalo indicado en lugar de reintentar de inmediato; un bucle de reintentos agresivo solo quema también la siguiente ventana.
* **No repartas llamadas entre claves** para esquivar el límite: es un único presupuesto por organización.
* **Prefiere los endpoints masivos y asíncronos** frente a muchas llamadas pequeñas (consulta [Importaciones frente a bulk](https://docs.retailgrid.io/es/api-reference/imports-vs-bulk.md)); mueven los mismos datos con muchas menos solicitudes.
* **Sondea con una cadencia razonable.** Para trabajos asíncronos, cada 5 a 10 s en trabajos activos y cada 30 a 60 s en trabajos en cola es más que suficiente (consulta [Convenciones ▸ Trabajos asíncronos](https://docs.retailgrid.io/es/api-reference/conventions.md)).

## Si el control de uso no está disponible

Si el propio servicio de control de uso no está disponible temporalmente, la API devuelve `503` con `{ "detail": { "code": "usage_enforcement_unavailable" } }`. Es una situación transitoria: reintenta tras una breve espera.

## Relacionado

* [Convenciones](https://docs.retailgrid.io/es/api-reference/conventions.md)
* [Errores](https://docs.retailgrid.io/es/api-reference/errors.md)
* [Importaciones frente a bulk](https://docs.retailgrid.io/es/api-reference/imports-vs-bulk.md)
* [Conexiones de IA (MCP)](https://docs.retailgrid.io/es/settings/ai-connections.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.