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

# Límites de uso

> El presupuesto de solicitudes de cada clave de API, los encabezados que lo informan y cómo esperar cuando lo alcanzas.

Cada clave de API tiene su propio presupuesto de solicitudes. El presupuesto se cuenta por clave, no por dirección IP ni por servidor: todas las máquinas que comparten una clave comparten su presupuesto, y dos claves nunca comparten uno.

## El presupuesto

| Parámetro | Valor actual |
| - | - |
| Solicitudes por ventana | **120** |
| Duración de la ventana | **60 segundos** |
| Se cuenta por | Clave de API |
| Se comparte entre | Las operaciones de `/v1` que usan la misma API key; MCP usa OAuth por separado |

La ventana es fija. Empieza con la primera solicitud que hace la clave después de que terminó la ventana anterior, y se reinicia 60 segundos después. Cuenta toda solicitud que pasa la autenticación, sea cual sea su resultado: un `200`, un `400`, un `404` o un `429` usan una unidad cada uno. Las solicitudes siguen contando mientras estás por encima del límite, pero no alargan la ventana.

Las solicitudes rechazadas con `401` `api_keys.invalid` o `403` `api_keys.scope_missing` se descartan antes de revisar el presupuesto: no cuentan y no traen encabezados de límite.

<Note>
  Estos son los valores actuales. Lee el presupuesto en los encabezados de la respuesta en lugar de fijarlo en tu código, para que tu integración siga cualquier cambio.
</Note>

## Encabezados en cada respuesta

Toda respuesta a una solicitud autenticada informa el estado del presupuesto en dos familias de encabezados: los muy usados `X-RateLimit-*` y los encabezados `RateLimit` del borrador de la IETF.

| Encabezado | Ejemplo | Significado |
| - | - | - |
| `X-RateLimit-Limit` | `120` | Solicitudes permitidas por ventana. |
| `X-RateLimit-Remaining` | `117` | Solicitudes que quedan en la ventana actual. `0` cuando se agotó el presupuesto. |
| `X-RateLimit-Reset` | `42` | **Segundos** hasta que se reinicia la ventana (no es una marca de tiempo). Como mínimo `1`. |
| `RateLimit-Policy` | `120;w=60` | El límite y la duración de la ventana en segundos. |
| `RateLimit` | `limit=120, remaining=117, reset=42` | La misma foto en un solo encabezado. |

```http theme={null}
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 117
X-RateLimit-Reset: 42
RateLimit-Policy: 120;w=60
RateLimit: limit=120, remaining=117, reset=42
x-request-id: 8d0e5b8a-2f4c-4e1b-9a7d-0c3b5e6f7a81
```

## Cuando superas el límite: `429`

La solicitud que supera el presupuesto se rechaza con `429 Too Many Requests`, un encabezado `Retry-After` con los segundos que debes esperar, los mismos encabezados de límite y un documento de problema con el código `common.too_many_requests`.

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/problem+json; charset=utf-8
Retry-After: 18
X-RateLimit-Limit: 120
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 18
RateLimit-Policy: 120;w=60
RateLimit: limit=120, remaining=0, reset=18
```

```json Accept-Language: es theme={null}
{
  "type": "https://docs.muveya.com/errors/common.too_many_requests",
  "title": "Demasiadas solicitudes",
  "status": 429,
  "detail": "Demasiadas solicitudes. Inténtalo de nuevo más tarde.",
  "instance": "/v1/orders",
  "code": "common.too_many_requests",
  "requestId": "5a1c7e2d-9b3f-4d6a-8e0c-2f4b6d8a0c1e"
}
```

Una solicitud rechazada no leyó ni cambió nada. Es seguro repetirla después de esperar los segundos de `Retry-After`.

## Cómo esperar

<CodeGroup>
  ```javascript JavaScript theme={null}
  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

  async function muveyaGet(url, headers, attempts = 5) {
    for (let attempt = 1; attempt <= attempts; attempt += 1) {
      const response = await fetch(url, { headers });
      if (response.status !== 429) return response;

      const retryAfter = Number(response.headers.get("retry-after") ?? "1");
      await sleep(Math.max(1, retryAfter) * 1000);
    }
    throw new Error("Rate limit: gave up after several attempts");
  }
  ```

  ```python Python theme={null}
  import time
  import requests

  def muveya_get(session: requests.Session, url: str, attempts: int = 5, **kwargs):
      for _ in range(attempts):
          response = session.get(url, timeout=30, **kwargs)
          if response.status_code != 429:
              return response
          retry_after = int(response.headers.get("Retry-After", "1"))
          time.sleep(max(1, retry_after))
      raise RuntimeError("Rate limit: gave up after several attempts")
  ```
</CodeGroup>

Buenos hábitos:

* **Espera lo que indica `Retry-After`** en cada `429`. Reintentar antes solo suma solicitudes rechazadas a la misma ventana.
* **Baja el ritmo antes de llegar al límite.** Cuando `X-RateLimit-Remaining` se acerque a `0`, espera `X-RateLimit-Reset` segundos antes de la siguiente ráfaga.
* **Usa páginas grandes.** Recorre las listas paginadas con `limit=200` (consulta [Paginación](/docs/es/api-reference/pagination)).
* **Guarda en caché lo que casi no cambia.** No necesitas leer sedes, bodegas y categorías en cada ejecución.
* **Consulta las exportaciones con calma.** Una consulta cada pocos segundos es suficiente mientras se genera una exportación (consulta [Exportaciones](/docs/es/api-reference/exports)).
* **No ejecutes procesos superpuestos** con la misma clave. Prográmalos uno después del otro.
* **Usa una clave por integración.** Cada clave tiene su propio presupuesto, así un proceso intenso no deja sin solicitudes a otro.

Si tu integración necesita un presupuesto mayor, escribe a [team@muveya.com](mailto:team@muveya.com) con el volumen de solicitudes que esperas.

## Páginas relacionadas

* [Errores](/docs/es/api-reference/errors)
* [Webhooks](/docs/es/api-reference/webhooks): consultas periódicas dentro del presupuesto
* [Scopes](/docs/es/api-reference/scopes)


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