Idempotencia y límites
Reintentos seguros con Idempotency-Key y límites de solicitudes.
Idempotencia
En facturación, repetir una solicitud por error puede significar dos comprobantes fiscales para una sola venta. Para evitarlo, las operaciones de escritura exigen el encabezado Idempotency-Key.
Idempotency-Key: factura-10482
Cómo funciona
- La primera solicitud con una clave se procesa normalmente.
- Si repites la misma clave con el mismo cuerpo, la API devuelve el resultado original sin crear nada nuevo ni consumir otra secuencia.
- Si repites la clave con un cuerpo distinto, la API responde
409 idempotency_conflict.
Cómo elegir la clave
Deriva la clave de un identificador estable de tu sistema: el número de factura interno, el número de pedido o el identificador de la transacción. Evita generarla al azar en cada intento, porque entonces un reintento parecería una operación nueva.
Cuándo reintentar
| Situación | Qué hacer |
|---|---|
| Error de red o tiempo de espera agotado | Reintenta con la misma clave. |
429 | Espera lo que indique Retry-After y reintenta con la misma clave. |
5xx | Reintenta con la misma clave, con esperas crecientes. |
4xx (excepto 429) | No reintentes sin corregir la solicitud. |
Límites de solicitudes
| Ámbito | Límite |
|---|---|
| Por API key | 60 solicitudes por minuto |
| Por cuenta | 300 solicitudes por minuto |
Al superar un límite la API responde 429 con el código rate_limited y el encabezado Retry-After, en segundos.
HTTP/2 429
Retry-After: 12
Content-Type: application/problem+json
{
"type": "https://docs.devsdesign.do/errors/rate_limited",
"title": "Límite de solicitudes excedido",
"status": 429,
"code": "rate_limited",
"request_id": "req_…"
}
Si tu operación necesita un volumen mayor, conversemos.
¿Algo no está claro o falta en esta página? Escríbenos por el centro de soporte.