Errores · Documentación de TradeCatalog

Los errores usan códigos HTTP normales y un cuerpo JSON con un code estable que puede comprobar en su código, y un message escrito para personas.

json

{
  "error": {
    "code": "validation_error",
    "message": "Some fields are invalid.",
    "issues": [
      {
        "path": "products.0.listPrice",
        "message": "Too small: expected number to be >=0"
      }
    ]
  }
}

issues solo está allí para validation_error. Cada problema tiene path que apunta al campo, con posiciones de lista contadas desde 0.

Códigos de errorEnlace a esta sección#

Estado	Código	Qué ocurrió	Qué hacer
400	`validation_error`	Un parámetro de consulta o campo del cuerpo está faltando o es inválido.	Corrija los campos listados en `issues`.
400	`invalid_json`	El cuerpo no es JSON válido.	Envíe JSON con `Content-Type: application/json`.
400	`invalid_request`	La solicitud es válida pero no está permitida en este momento, por ejemplo, marcar un nuevo pedido como completado.	Lea `message`; no intente de nuevo sin cambios.
401	`unauthorized`	Clave de API faltante, desconocida o revocada.	Compruebe el encabezado `Authorization: Bearer` y que la clave aún esté activa.
401	`key_owner_removed`	La persona que creó la clave ya no está en el espacio de trabajo.	Cree una nueva clave desde alguien que aún tenga acceso.
403	`insufficient_scope`	Una clave de solo lectura intentó escribir.	Use una clave de lectura y escritura.
403	`read_only`	Las escrituras de API no están disponibles en el plan Free actual del espacio de trabajo.	El propietario gestiona el plan en el sitio web. Las claves existentes aún leen.
403	`forbidden`	La persona que creó la clave no tiene permiso para hacer eso.	Pida a un propietario del espacio de trabajo, o cree una clave desde alguien con ese permiso.
403	`workspace_suspended`	TradeCatalog ha suspendido el espacio de trabajo. El propietario ha recibido un correo electrónico con la razón.	Las claves funcionan nuevamente cuando se levanta la suspensión.
404	`not_found`	No existe ese punto de conexión, o no existe ese producto, cliente, pedido o cambio de precio en este espacio de trabajo.	Verifique el id, SKU o código de cuenta.
405	`method_not_allowed`	La ruta existe pero no con este método.	Use un método del encabezado `Allow`.
429	`rate_limited`	Más de 120 solicitudes por minuto con esta clave.	Espere `Retry-After` segundos (60), luego intente de nuevo.
500	`internal_error`	Algo salió mal por nuestra parte.	Vuelva a intentarlo con backoff. Si sigue ocurriendo, contacte al soporte.

Los IDs de otro espacio de trabajo siempre devuelven 404 not_found, nunca datos de otra persona.

ReintentoEnlace a esta sección#

Vuelva a intentar las respuestas 429 y 5xx con backoff. No intente nuevamente otras respuestas 4xx: fallarán de la misma manera.

Todos los escritos de la API son seguros para repetir: PUT coincide filas por SKU o código de cuenta, y PATCH /orders/{id} falla con invalid_request si el pedido ya ha avanzado. Por lo tanto, un reintento después de un tiempo de espera de red no duplicará nada.

async function api(path, init = {}, attempt = 0) {
  const res = await fetch(`https://tradecatalog.app/api/v1${path}`, {
    ...init,
    headers: {
      Authorization: `Bearer ${process.env.TRADECATALOG_API_KEY}`,
      'Content-Type': 'application/json',
      ...init.headers,
    },
  })
  if ((res.status === 429 || res.status >= 500) && attempt < 5) {
    const wait = Number(res.headers.get('Retry-After')) || 2 ** attempt
    await new Promise((resolve) => setTimeout(resolve, wait * 1000))
    return api(path, init, attempt + 1)
  }
  const body = await res.json()
  if (!res.ok) {
    const error = new Error(`${body.error.code}: ${body.error.message}`)
    error.status = res.status
    error.code = body.error.code
    error.issues = body.error.issues
    throw error
  }
  return body
}

Mensajes comunesEnlace a esta sección#

Solicitud	Estado y mensaje
`GET /prices` con un SKU desconocido	`404` “No hay producto con SKU HX-9999”
Cualquier endpoint con un cliente desconocido	`404` “Cliente OAK99 no encontrado”
`PATCH /orders/{id}` nuevo → completado	`400` “Un pedido recibido no puede marcarse como completado”
`PATCH /orders/{id}` a cancelado sin nota	`400` “Proporcione un motivo para la cancelación”
`PUT /products` con el mismo SKU dos veces	`400` error de validación “SKU duplicado hx-8510”