Límites de uso

Cada llave de API, cada conexión de IA y cada organización tiene un presupuesto de llamadas por minuto, según el tipo de llamada:

Llamadas por minuto	Por llave de API	Por conexión de IA	Por organización
Lectura: un `GET`	, lecturas y escrituras juntas
Escritura: cualquier otro método	compartidas con las lecturas
Masiva: una operación que cambia muchos registros en una llamada

Una llamada gasta del presupuesto de su llave, y luego del de su organización. El presupuesto de la organización lo comparten todas sus llaves y conexiones de IA, así que un programa muy activo puede frenar a los demás: da a cada programa su propia llave y reparte sus llamadas.
Las personas en la aplicación no gastan nada de él. El trabajo de una persona en la aplicación nunca toma de estos presupuestos, así que un programa que los agota nunca deja fuera a tu equipo.
Los presupuestos se recargan de forma continua, no al empezar cada minuto, y guardan solo unos segundos de llamadas a la vez: un ritmo parejo rinde más que las ráfagas.

Saber cuánto queda

Obtener la credencial que llama responde los limits de tu llave y sus llamadas remaining de cada tipo, lo menor entre lo que aún tienen su propio presupuesto y el de su organización. No cuenta para ningún límite ni ocupa lugar entre las llamadas en curso, así que puedes llamarla cuando lo necesites.

Al pasarse de un límite

Una llamada que pasa un presupuesto responde 429 con el código core.rate_limited y una cabecera Retry-After, los segundos enteros que hay que esperar. No hizo nada: espera ese tiempo y vuelve a enviarla, nunca en un bucle sin pausa.

# --retry sigue Retry-After ante un 429 o un 503
curl --retry 3 "https://app.readyforcommerce.com/api/v1/orgs/$RFC_ORG_ID/core/org" \
  --header "Authorization: Bearer $RFC_API_KEY"

import os
import time

import requests

url = f"https://app.readyforcommerce.com/api/v1/orgs/{os.environ['RFC_ORG_ID']}/core/org"
headers = {"Authorization": f"Bearer {os.environ['RFC_API_KEY']}"}
for _ in range(3):
    response = requests.get(url, headers=headers)
    if response.status_code not in (429, 503):
        break
    time.sleep(int(response.headers["Retry-After"]))
print(response.json())

<?php
$url = 'https://app.readyforcommerce.com/api/v1/orgs/' . getenv('RFC_ORG_ID') . '/core/org';
for ($attempt = 0; $attempt < 3; $attempt++) {
    $wait = 0;
    $curl = curl_init($url);
    curl_setopt_array($curl, [
        CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('RFC_API_KEY')],
        CURLOPT_RETURNTRANSFER => true,
        CURLOPT_HEADERFUNCTION => function ($curl, $line) use (&$wait) {
            if (stripos($line, 'Retry-After:') === 0) {
                $wait = (int) trim(substr($line, 12));
            }
            return strlen($line);
        },
    ]);
    $body = curl_exec($curl);
    $status = curl_getinfo($curl, CURLINFO_RESPONSE_CODE);
    if ($status !== 429 && $status !== 503) {
        break;
    }
    sleep($wait);
}
echo $body;

const url = `https://app.readyforcommerce.com/api/v1/orgs/${process.env.RFC_ORG_ID}/core/org`;
let response;
for (let attempt = 0; attempt < 3; attempt++) {
  response = await fetch(url, { headers: { Authorization: `Bearer ${process.env.RFC_API_KEY}` } });
  if (response.status !== 429 && response.status !== 503) break;
  const seconds = Number(response.headers.get('Retry-After'));
  await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
}
console.log(await response.json());

Llamadas en curso

Mantén como máximo llamadas de las llaves y conexiones de IA de tu organización en curso a la vez. Una llamada más allá de ellas puede responder 429 core.rate_limited antes de hacer nada, con su propio Retry-After. Para leer más rápido, pide páginas más grandes en lugar de más llamadas a la vez.

Trabajos sin terminar

El trabajo largo, como una importación o una exportación, corre como un trabajo: su llamada responde 202 Accepted con un jobId, que Obtener un trabajo sigue hasta que termina. Una organización tiene como máximo trabajos sin terminar, quien sea que los haya iniciado: en espera, en pausa o corriendo. Un inicio de una llave o de una IA más allá de ellos responde 429 con el código core.job_limit_reached y un Retry-After de segundos, y no inicia nada. El inicio de una persona en la aplicación nunca se rechaza. El archivo de un trabajo, como el de una exportación, se lee mediante un enlace de Obtener el enlace de un archivo del trabajo, que funciona durante minutos: pide uno nuevo cuando venza.

Repite una escritura sin riesgo

Una escritura cuya respuesta nunca llegó, porque la conexión se cortó o tardó demasiado, puede haber ocurrido o no. Envíala con una cabecera Idempotency-Key, un valor tuyo de como máximo caracteres, como un UUID hecho para esa sola escritura, y envía el mismo valor en cada reintento:

IDEMPOTENCY_KEY=$(uuidgen) # una por escritura; la misma en cada reintento

curl --request POST \
  "https://app.readyforcommerce.com/api/v1/orgs/$RFC_ORG_ID/core/jobs/$JOB_ID/cancel" \
  --header "Authorization: Bearer $RFC_API_KEY" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY"

import os
import uuid

import requests

idempotency_key = str(uuid.uuid4())  # una por escritura; la misma en cada reintento
response = requests.post(
    f"https://app.readyforcommerce.com/api/v1/orgs/{os.environ['RFC_ORG_ID']}/core/jobs/{os.environ['JOB_ID']}/cancel",
    headers={
        "Authorization": f"Bearer {os.environ['RFC_API_KEY']}",
        "Idempotency-Key": idempotency_key,
    },
)
print(response.json())

<?php
$idempotencyKey = bin2hex(random_bytes(16)); // una por escritura; la misma en cada reintento
$curl = curl_init(
    'https://app.readyforcommerce.com/api/v1/orgs/' . getenv('RFC_ORG_ID') . '/core/jobs/' . getenv('JOB_ID') . '/cancel'
);
curl_setopt_array($curl, [
    CURLOPT_POST => true,
    CURLOPT_HTTPHEADER => [
        'Authorization: Bearer ' . getenv('RFC_API_KEY'),
        'Idempotency-Key: ' . $idempotencyKey,
    ],
    CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($curl);

const idempotencyKey = crypto.randomUUID(); // una por escritura; la misma en cada reintento
const response = await fetch(
  `https://app.readyforcommerce.com/api/v1/orgs/${process.env.RFC_ORG_ID}/core/jobs/${process.env.JOB_ID}/cancel`,
  {
    method: 'POST',
    headers: {
      Authorization: `Bearer ${process.env.RFC_API_KEY}`,
      'Idempotency-Key': idempotencyKey,
    },
  },
);
console.log(await response.json());

La primera llamada hace la escritura; un reintento con el mismo valor y la misma petición responde la respuesta de la primera, sin hacerla otra vez, durante horas.
Mientras la primera llamada sigue corriendo, un reintento responde 409 core.idempotency_in_progress: espera y reintenta.
El mismo valor con otra petición, otro cuerpo u otra ruta, responde 422 core.idempotency_mismatch.
Cada valor es de tu credencial: la llamada de otra llave de API con el mismo valor es una llamada aparte.
Un valor vacío o demasiado largo responde 400 core.bad_request.
Una llamada que falló no guarda nada, así que su reintento vuelve a correr.

Estas escrituras respetan un Idempotency-Key; en cualquier otra no cambia nada: Cancelar un trabajo, Restaurar una versión, Iniciar una importación, Inspeccionar un archivo de importación, Revisar una importación, Traer un archivo desde una URL, Generar los resultados de una importación, Iniciar una exportación, Crear una plantilla de exportación, Crear una vista guardada, Conectar una tienda, Crear un producto y Duplicar un producto.

Primeros pasos

Uso de la API

Asistentes de IA

Saber cuánto queda

Al pasarse de un límite

Llamadas en curso

Trabajos sin terminar

Repite una escritura sin riesgo