DEVSDESIGN — DEVELOPERS & DESIGN

API v1 · contrato 1.0.0

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.

Encabezado obligatorio en escrituras
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ónQué hacer
Error de red o tiempo de espera agotadoReintenta con la misma clave.
429Espera lo que indique Retry-After y reintenta con la misma clave.
5xxReintenta con la misma clave, con esperas crecientes.
4xx (excepto 429)No reintentes sin corregir la solicitud.

Límites de solicitudes

ÁmbitoLímite
Por API key60 solicitudes por minuto
Por cuenta300 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.

Respuesta 429
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.