> ## Documentation Index
> Fetch the complete documentation index at: https://docs.lapyme.com.ar/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```json theme={null}
{
  "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

```typescript theme={null}
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.