Gestion de errores

La API The Trade Hub utiliza codigos de estado HTTP estandar para indicar el exito o el fallo de una solicitud. Los codigos en el rango 2xx indican exito, los codigos 4xx un error del cliente, y los codigos 5xx un error del servidor.

Formato de las respuestas de error

Todos los errores devuelven un cuerpo JSON con un campo detail que describe el problema:

{
  "detail": "Descripcion del error"
}

Para los errores de validacion (422), el formato incluye detalles adicionales:

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Codigos de error

401 Unauthorized

Clave API invalida o faltante. Verifique que el encabezado X-API-Key este presente y contenga una clave valida.

{
  "detail": "Clave API invalida o faltante"
}

Causas comunes:

• Encabezado X-API-Key ausente en la solicitud
• Clave API expirada o revocada
• Clave copiada con espacios o caracteres adicionales
• Clave API desactivada por un administrador de la organizacion

Resolucion:

• Verifique que el encabezado este correctamente escrito (X-API-Key, no X-Api-Key)
• Compruebe que la clave esta activa en el panel de desarrollador
• Regenere la clave si es necesario

402 Payment Required

Saldo de creditos insuficiente o limite de gasto alcanzado. Su organizacion se ha quedado sin creditos o ha alcanzado su limite de gasto mensual.

{
  "detail": "insufficient balance"
}

Causas comunes:

• Saldo de creditos prepagados agotado (modo balance)
• Limite de gasto mensual alcanzado (modo invoice)

Headers adicionales:

• X-Balance-Cents: saldo actual en centimos (modo balance)
• X-Spending-Limit / X-Spending-Current: limite y gasto actual (modo invoice)

Resolucion:

• Recargue su saldo de creditos desde el panel de facturacion
• Ajuste su limite de gasto si es necesario
• Active la recarga automatica para evitar interrupciones

403 Forbidden

Permisos insuficientes. Su clave API no tiene los derechos necesarios para esta operacion.

{
  "detail": "Permisos insuficientes para esta operacion"
}

Causas comunes:

• Intento de acceso a un recurso de otra organizacion
• Clave API con permisos restringidos
• Scope de la clave API insuficiente para este recurso

Resolucion:

• Verifique que el recurso pertenece a su organizacion
• Contacte al administrador de su organizacion para ajustar los permisos

404 Not Found

Recurso no encontrado. El identificador especificado no corresponde a ningun recurso existente.

{
  "detail": "Job no encontrado"
}

Causas comunes:

• Identificador de job o lote incorrecto
• Recurso eliminado
• Identificador de otra organizacion

Resolucion:

• Verifique el identificador en su solicitud
• Utilice el endpoint historial para encontrar el recurso correcto

422 Unprocessable Entity

Error de validacion. El cuerpo de la solicitud no respeta el formato esperado.

{
  "detail": [
    {
      "loc": ["body", "content"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}

Causas comunes:

• Campo obligatorio faltante (content)
• Tipo de datos incorrecto (cadena en lugar de array)
• Valor fuera de los limites aceptados
• Formato JSON invalido en el cuerpo de la solicitud

Resolucion:

• Consulte la documentacion del endpoint para los parametros requeridos
• Valide su JSON antes del envio
• Verifique los tipos de datos de cada campo

429 Too Many Requests

Limite de velocidad alcanzado. Ha enviado demasiadas solicitudes en la ventana temporal.

{
  "detail": "Limite de velocidad alcanzado. Reintente en 12 segundos."
}

Resolucion:

• Espere la duracion indicada en el encabezado Retry-After
• Implemente un backoff exponencial
• Utilice la clasificacion por lotes para reducir el numero de solicitudes

500 Internal Server Error

Error interno del servidor. Ocurrio un error inesperado en el lado del servidor.

{
  "detail": "Error interno del servidor"
}

Resolucion:

• Reintente la solicitud despues de unos segundos
• Si el error persiste, contacte al soporte con el identificador de solicitud
• Consulte la pagina de estado para incidentes en curso

503 Service Unavailable

Servicio temporalmente no disponible. El servicio esta en mantenimiento o sobrecargado.

{
  "detail": "Servicio temporalmente no disponible. Reintente mas tarde."
}

Resolucion:

• Reintente despues de unos minutos
• Consulte la pagina de estado para mantenimientos planificados
• Implemente un mecanismo de cola para las solicitudes fallidas

Tabla resumen

Gestion recomendada

import httpx

client = httpx.Client(
    base_url="https://api.thetradehub.eu",
    headers={"X-API-Key": "th_live_su_clave_api"},
)

response = client.post("/v1/classify/jobs", json={
    "content": "Auriculares Bluetooth inalambricos"
})

match response.status_code:
    case 201:
        job = response.json()
        print(f"Job creado: {job['id']}")
    case 401:
        print("Error de autenticacion. Verifique su clave API.")
    case 402:
        print("Saldo insuficiente. Recargue sus creditos.")
    case 422:
        errors = response.json()["detail"]
        for error in errors:
            print(f"Validacion: {error['loc']} - {error['msg']}")
    case 429:
        retry_after = int(response.headers.get("Retry-After", 10))
        print(f"Rate limited. Reintente en {retry_after}s.")
    case code if code >= 500:
        print(f"Error del servidor ({code}). Reintente mas tarde.")
    case _:
        print(f"Error inesperado: {response.status_code}")

const response = await fetch("https://api.thetradehub.eu/v1/classify/jobs", {
  method: "POST",
  headers: {
    "X-API-Key": "th_live_su_clave_api",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ content: "Auriculares Bluetooth inalambricos" }),
});

switch (response.status) {
  case 201: {
    const job = await response.json();
    console.log(`Job creado: ${job.id}`);
    break;
  }
  case 401:
    console.error("Error de autenticacion. Verifique su clave API.");
    break;
  case 402:
    console.error("Saldo insuficiente. Recargue sus creditos.");
    break;
  case 422: {
    const { detail } = await response.json();
    for (const error of detail) {
      console.error(`Validacion: ${error.loc.join(".")} - ${error.msg}`);
    }
    break;
  }
  case 429: {
    const retryAfter = response.headers.get("Retry-After") || "10";
    console.warn(`Rate limited. Reintente en ${retryAfter}s.`);
    break;
  }
  default:
    if (response.status >= 500) {
      console.error(`Error del servidor (${response.status}). Reintente mas tarde.`);
    } else {
      console.error(`Error inesperado: ${response.status}`);
    }
}