> ## Documentation Index
> Fetch the complete documentation index at: https://dev.acpay.do/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores y límites

> Forma de los errores, códigos, reintentos y límites mensuales.

## Forma de los errores

Todas las respuestas de error tienen la misma forma:

```json theme={null}
{
  "error": {
    "status": 400,
    "message": "La solicitud no es válida.",
    "details": [
      "items.0.quantity: debe ser un número entero.",
      "dueDate: es obligatoria cuando paymentType es credit."
    ]
  }
}
```

`details` aparece solo cuando hay errores por campo. Cada respuesta, también las de error, trae `X-Request-Id`: inclúyelo cuando nos reportes un problema. Puedes enviar el tuyo en la solicitud.

## Códigos

| Código | Significado | ¿Reintentar? |
| - | - | - |
| `400` | Solicitud inválida: cuerpo, parámetros o `Idempotency-Key`. | No sin corregirla. Después de corregirla, con la misma `Idempotency-Key`. |
| `401` | Llave ausente, con formato inválido, de otro ambiente, vencida o revocada. | No. Revisa la llave y la URL base. |
| `403` | La llave no tiene permiso para esta operación, o el comercio está inactivo. | No. |
| `404` | El documento, webhook o secuencia no existe o no es de tu comercio. | No. |
| `409` | Una solicitud con la misma `Idempotency-Key` sigue en curso, o el estado del recurso no permite la operación (por ejemplo, anular un documento que no está aceptado, o registrar una secuencia de un tipo que ya tiene). | Si es por la `Idempotency-Key`, sí: con la misma llave, en unos segundos. Si es por el estado, no. |
| `422` | La `Idempotency-Key` ya se usó con otra solicitud. | No: usa una llave nueva. |
| `429` | Límite de solicitudes por minuto o límite mensual de comprobantes. | Ver abajo. |
| `5xx` (`500`, `502`, `503`, `504`) | Error inesperado o falta de disponibilidad del servicio de facturación. No se sabe si la solicitud llegó. | Sí, con la misma `Idempotency-Key`: ningún `5xx` se guarda y el reintento no emite un segundo comprobante. |

## Los dos `429`

* **Solicitudes por minuto de tu llave:** el `429` trae `Retry-After` (segundos a esperar) y, cuando están disponibles, los encabezados `X-RateLimit-*`. Espera y reintenta.
* **Comprobantes por mes de cada tipo de e-CF** (solo al emitir): el `429` **no** trae `Retry-After` y su mensaje dice cuándo se renueva. No se resuelve reintentando: espera la renovación o pide ampliarlo.

```json theme={null}
{
  "error": {
    "status": 429,
    "message": "Alcanzaste el límite mensual de comprobantes 31 (500). Se renueva el 1 de octubre; para ampliarlo contacta a AC-PAY."
  }
}
```

Ningún `429` se guarda como respuesta idempotente: cuando puedas volver a emitir, reintenta con la misma `Idempotency-Key`.

## Límites mensuales

`GET /v1/limits` muestra, por tipo de e-CF, tu límite, lo emitido y lo disponible en el mes.

* Solo aparecen los tipos con límite; un tipo que no aparece no tiene límite.
* El mes se cuenta en hora de República Dominicana y se renueva al inicio del mes siguiente (`resetsAt`).
* Te avisamos por correo al llegar al 80 % y al 100 % del límite de cada tipo, una vez por mes.
* Consultar, descargar y anular documentos sigue funcionando con el límite alcanzado, y reintentar un documento ya emitido no vuelve a contar.
* **En el sandbox los límites no se aplican** (`enforced: false`).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.