Errores

Cómo interpretar errores de la API de La Pyme, usar request_id y distinguir errores corregibles de reintentos.

La API usa el status HTTP como señal de éxito o error. Cuando una request falla, la respuesta incluye request_id para soporte y un objeto error estructurado.

{
  "request_id": "req_123",
  "error": {
    "type": "invalid_request_error",
    "code": "INVALID_REQUEST",
    "message": "Descripción del error",
    "retryable": false,
    "details": []
  }
}

Campos del error

Campo	Descripción
type	Familia del error, por ejemplo authentication_error, authorization_error, invalid_request_error, business_error o rate_limit_error.
code	Código estable para manejar el error programáticamente.
message	Mensaje legible para logs, soporte o interfaces internas.
retryable	Indica si tiene sentido reintentar la misma request sin cambiar el payload.
details	Lista opcional de detalles por campo, header o regla de negocio.

Cada ítem de error.details puede incluir:

Campo	Descripción
field	Path lógico del campo o header relacionado.
code	Código estable para ese detalle.
message	Explicación legible del problema.

Códigos comunes

Código	Causa	Qué hacer
AUTHENTICATION_REQUIRED	Falta la credencial bearer, es inválida o expiró.	Enviá Authorization: Bearer <api_key> o regenerá la credencial.
FORBIDDEN	La credencial no tiene permisos para esa operación.	Revisá los scopes de la API key o del token delegado.
INVALID_REQUEST	Parámetros, body o headers inválidos.	Corregí nombres, tipos y campos requeridos.
NOT_FOUND	El recurso solicitado no existe o no pertenece a la organización autenticada.	Verificá el ID y la organización de la credencial.
PRECONDITION_FAILED	La operación no puede ejecutarse por una regla de negocio.	Revisá details y corregí el estado o el payload.
IDEMPOTENCY_CONFLICT	Se reutilizó una Idempotency-Key con otro payload.	Reintentá con la misma key solo si el payload es idéntico; si cambió, usá una key nueva.
RATE_LIMITED	La organización superó la cuota.	Respetá el header Retry-After.

Manejar errores en TypeScript

const response = await fetch("https://api.lapyme.com.ar/api/v1/products?limit=10", {
  headers: {
    Authorization: `Bearer ${process.env.LAPYME_API_KEY}`,
  },
});

const data = await response.json();

if (!response.ok) {
  console.error("Request ID:", data.request_id);
  console.error("Código:", data.error.code);
  console.error("Mensaje:", data.error.message);
  throw new Error(data.error.message);
}

console.log("Productos:", data.data);

Cuándo reintentar

Reintentá la misma request cuando:

1. Recibís un error 5xx.
2. Recibís RATE_LIMITED y ya esperaste el tiempo indicado en Retry-After.
3. La conexión falló antes de recibir una respuesta.

Para escrituras idempotentes, reintentá con la misma Idempotency-Key. Para errores 4xx de validación o permisos, corregí el problema antes de volver a enviar.