Errores

​

Códigos de estado

​

Límite de uso de la organización (429)

{
  "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
  }
}

• unit es uno de requests, active_work, bytes o calls.
• reset_at es el momento en que se repone el presupuesto; retry_after es la misma espera en segundos y coincide con la cabecera Retry-After.
• El presupuesto se comparte entre claves de API, usuarios y el conector MCP (consulta Convenciones ▸ Límites de uso), así que cambiar de clave no restaura el acceso: espera al reinicio.

​

Forma de los errores de validación

{
  "detail": [
    {
      "loc": ["body", "items", 0, "regular_price"],
      "msg": "field required",
      "type": "missing"
    },
    {
      "loc": ["body", "items", 1, "observed_at"],
      "msg": "input should be a valid datetime",
      "type": "datetime_parsing"
    }
  ]
}

• loc - ruta JSON al campo problemático, incluidos los índices de los arrays.
• msg - mensaje legible para personas.
• type - código de error legible por máquinas (por ejemplo, missing, string_too_long, value_error).

​

Endpoints masivos: errores por elemento

{
  "results": [
    { "index": 0, "ok": true,  "id": "1c2d..." },
    { "index": 1, "ok": false, "code": "validation_error", "message": "product_name too long" }
  ]
}

​

Casos 422 comunes por familia de endpoints

• Products - falta item_id, falta sku, o un campo decimal no se puede interpretar.
• Product store - falta item_id, store_id o current_price; store_id hace referencia a una tienda desconocida.
• Transactions - falta item_id, transaction_timestamp mal formado, campo decimal que no se puede interpretar.
• Competitor prices - falta uno de los cuatro campos obligatorios (competitor_name, observed_at, regular_price, effective_price).
• Imports (CSV) - archivo no adjunto, archivo vacío, archivo que no es UTF-8, fila de cabecera ausente.

​

Estrategia de reintentos

• Endpoints idempotentes (POST /v1/<entity>/{entity_id}, PATCH, DELETE, /bulk) - reintenta ante 5xx y ante errores de transporte con retroceso exponencial (empieza en 1 s, tope de 30 s, máximo 5 intentos).
• POST /v1/competitor_prices - es una creación no idempotente (sin id en la ruta). Reintentar tras una respuesta exitosa creará una fila duplicada. Comprueba el resultado de la red antes de reintentar.
• Importaciones asíncronas - si POST /v1/imports/* falla, reintenta la carga. Si tiene éxito y el trabajo (job) posterior falla, corrige el CSV y envía un trabajo nuevo en lugar de reintentar la misma carga.