Errores

Todos los puntos de conexión de claves API devuelven datos en formato JSON. En cualquier respuesta que no sea del código 2xx, el cuerpo tiene la misma estructura:

{
  "success": false,
  "error": "<human-readable message>"
}

Algunos errores incluyen contexto adicional (p. ej., créditos (por un error de cuota 429). El código de estado HTTP es la fuente de referencia: toma una decisión en función del estado y, a continuación, lee error para su visualización o registro.

Referencia de códigos de estado n.º

Distinguir entre ambos 429 casos#

A 429 siempre significa «deja de enviar por ahora», pero ¿por qué? importa.

Límite de solicitudes (60 por minuto, por usuario):

{
  "success": false,
  "error": "Rate limit exceeded. Max 60 requests per minute."
}

Agotamiento mensual del crédito (20 000 al mes, por usuario):

{
  "success": false,
  "error": "Monthly credit limit reached (20000). Resets next month.",
  "credits": { "used": 20000, "limit": 20000, "remaining": 0 }
}

Depende de la presencia del créditos objeto, o en una coincidencia de subcadena para «Límite de crédito mensual». Véase Límites de velocidad y Créditos y facturación para la estrategia de recuperación en cada caso.

Patrón de gestión de errores (Node.js)#

async function whFetch(path, init = {}) {
  const res = await fetch(`${ORIGIN}${path}`, {
    ...init,
    headers: { 'X-API-Key': process.env.WH_API_KEY, ...(init.headers || {}) },
  });

  let body = null;
  try { body = await res.json(); } catch { /* non-JSON, leave null */ }

  if (res.ok) return body;

  const error = (body && body.error) || res.statusText;

  if (res.status === 401) throw new Error(`Auth failed: ${error}`);
  if (res.status === 403) throw new Error(`Plan required: ${error}`);
  if (res.status === 404) throw new Error(`Unknown endpoint: ${path}`);
  if (res.status === 429) {
    const retryable = body && body.credits ? false : true; // monthly quota is not retryable today
    const err = new Error(error);
    err.retryable = retryable;
    throw err;
  }
  if (res.status >= 500) {
    const err = new Error(`Upstream error: ${error}`);
    err.retryable = true;
    throw err;
  }
  throw new Error(`HTTP ${res.status}: ${error}`);
}

Patrón de gestión de errores (Python)#

import os, requests

def wh_fetch(path, **kwargs):
    r = requests.request(
        method=kwargs.pop("method", "GET"),
        url=f"{ORIGIN}{path}",
        headers={"X-API-Key": os.environ["WH_API_KEY"], **kwargs.pop("headers", {})},
        **kwargs,
    )

    body = None
    try:
        body = r.json()
    except ValueError:
        pass

    if r.ok:
        return body

    error = (body or {}).get("error") or r.reason

    if r.status_code == 401:
        raise PermissionError(f"Auth failed: {error}")
    if r.status_code == 403:
        raise PermissionError(f"Plan required: {error}")
    if r.status_code == 429:
        is_quota = bool((body or {}).get("credits"))
        raise RuntimeError(f"Rate limited (quota={is_quota}): {error}")
    if r.status_code >= 500:
        raise RuntimeError(f"Upstream error: {error}")

    raise RuntimeError(f"HTTP {r.status_code}: {error}")

Formato de respuesta frente a código de estado HTTP#

• Errores relacionados con la protección de claves API con límite de uso (401, 403, límite 429, frase genérica 500) siempre devuelven JSON con éxito: falso y un estado HTTP correspondiente.
• Algunos controladores JSON (especialmente los paquetes de datos de gran tamaño de TikTok Shop) pueden devolver un código de estado HTTP 200 con un cuerpo que incluye indicadores de nivel empresarial: lee siempre el esquema de ese punto final en lugar de dar nada por sentado éxito solo rastrea el protocolo HTTP.

¿HTML en lugar de JSON? Conjunto de rutas programáticas con medición Tipo de contenido: application/json. El código HTML suele indicar un servidor incorrecto, una página de error del proxy o una ruta que nunca llegó a la aplicación; véase Solución de problemas.

Notificación de errores#

Si te topas con un 500 o una respuesta que contradiga la documentación:

1. Anota la URL de la solicitud, el método, los encabezados (oculta tu clave) y el cuerpo.
2. Registra el estado y el cuerpo de la respuesta.
3. Fíjate en la fecha y hora.
4. Envía el paquete al servicio de asistencia; el equipo podrá cotejarlo con los registros del servidor mediante el ID de usuario y la marca de tiempo.