01 / Guía
Primero decide si debes corregir, esperar o conciliar
El código HTTP indica la familia del problema y error.code permite decidir la acción concreta. No conviertas cualquier respuesta distinta de 200 en el mismo reintento automático.
Una política sencilla separa errores de entrada, límites temporales y resultados inciertos. Esa separación protege el pedido y también evita llenar la API con solicitudes que no pueden cambiar de resultado.
| Respuesta | Qué significa | Qué debe hacer tu integración |
|---|---|---|
| 400 VALIDATION_ERROR | La solicitud no cumple el contrato. | Corrige los campos; no repitas el mismo cuerpo. |
| 401 o 403 | La credencial falta, venció o no tiene alcance. | Corrige la autenticación o los permisos antes de repetir. |
| 402 INSUFFICIENT_BALANCE | El saldo disponible no cubre la operación. | Agrega saldo y crea una nueva intención con otra llave. |
| 404 RESOURCE_NOT_FOUND | El recurso no existe en esa organización o modo. | Revisa identificador, cuenta y llave; no pruebes IDs al azar. |
| 409 de idempotencia | La misma llave sigue en uso o se aplicó a otra solicitud. | Distingue IN_USE de REUSED antes de actuar. |
| 429 RATE_LIMIT_EXCEEDED | La clase de solicitud agotó su ventana actual. | Espera Retry-After y reduce la frecuencia. |
| 5xx o corte de red | El resultado puede ser incierto. | No asumas éxito ni falla; conserva contexto y concilia antes de una nueva intención. |
02 / Guía
Usa una llave por intención, no por intento
Idempotency-Key es opcional en las mutaciones de SendIt. Conviene incluirla en compras de guía, anulaciones y otras operaciones que no quieres ejecutar dos veces si la red se interrumpe.
Genera una llave única cuando comienza la intención de negocio y conserva exactamente la misma para sus reintentos de transporte. Dentro de las siguientes 24 horas, SendIt devuelve el resultado original —éxito o falla— sin volver a ejecutar la operación. Una respuesta reproducida incluye Idempotent-Replayed: true.
Mismo pedido, misma operación y mismo cuerpo: conserva la llave.
Otra guía, otro endpoint o un cuerpo distinto: genera una llave nueva.
Usa entre 1 y 255 caracteres imprimibles; UUID v4 es una opción práctica.
Nunca reutilices una llave de producción para representar una intención distinta.
03 / Guía
Protege la compra de la guía desde la primera solicitud
La llave debe existir antes de llamar a la API y guardarse junto con la referencia del pedido. Si tu proceso pierde la conexión, puede reconstruir la solicitud idéntica en lugar de inventar una operación nueva.
El encabezado no sustituye la conciliación de tu propio sistema. Conserva shipmentId, rateId y el propósito de la llave para saber qué resultado esperas recuperar.
POST /v1/shipments/:id/label
X-API-Key: sk_test_...
SendIt-Version: 2026-05-01
Idempotency-Key: 7ad6a2a5-0f7a-4bc0-9387-93a56c3b2275
Content-Type: application/json
{
"rateId": "DHL_standard_a1b2c3",
"labelFormat": "PDF"
}04 / Guía
Aplica un flujo de reintento que conserve la intención
Limita cada reintento, agrega una espera creciente y una pequeña variación aleatoria para que muchas solicitudes no regresen al mismo tiempo. El objetivo no es insistir hasta recibir 200: es llegar a un resultado conocido sin duplicar el efecto.
- 01
Recibiste 2xx
Guarda el recurso y termina la intención; no vuelvas a comprar.
- 02
Recibiste un 4xx corregible
Resuelve datos, permisos, saldo o estado antes de crear una nueva intención.
- 03
Recibiste 429
Espera los segundos de Retry-After y repite sin aumentar la frecuencia.
- 04
No recibiste respuesta
Repite el mismo método, ruta, cuerpo e Idempotency-Key.
- 05
Recibiste un 5xx con llave
Trátalo como resultado incierto; conserva la llave y revisa el recurso o historial antes de generar otra.
- 06
Sigues sin certeza
Detén la automatización y entrega requestId, shipmentId y la llave a conciliación sin exponer la credencial.
05 / Guía
Distingue los conflictos antes de cambiar de llave
IDEMPOTENCY_KEY_IN_USE significa que la misma llave todavía está bloqueada por una solicitud en curso o por un resultado que necesita conciliación. Espera brevemente y repite la solicitud idéntica con esa misma llave; si el conflicto persiste, revisa el recurso y no abras otra intención.
IDEMPOTENCY_KEY_REUSED significa que la llave se presentó con una ruta, consulta o cuerpo diferente. No fuerces el reintento: confirma cuál era la intención original y usa una llave nueva únicamente para una operación realmente distinta.
Si una compra de guía ya está en curso, SHIPMENT_LABEL_IN_PROGRESS protege al envío frente a otra intención incompatible. Consulta el estado existente; no abras una segunda compra para vencer el conflicto.
06 / Guía
Lee los límites como tres presupuestos separados
SendIt separa lecturas, escrituras y cotizaciones por minuto. Así, una ráfaga de cotizaciones no consume el presupuesto destinado a comprar guías. Cada respuesta informa el límite de la clase que atendió esa solicitud.
X-RateLimit-Reset usa segundos Unix. Cuando recibas 429, Retry-After indica cuántos segundos esperar; respétalo antes de aplicar tu siguiente demora creciente.
X-RateLimit-Limit: presupuesto de la clase actual.
X-RateLimit-Remaining: solicitudes disponibles en esa ventana.
X-RateLimit-Reset: momento de reinicio en segundos Unix.
Las llaves sk_test_ usan presupuestos aislados equivalentes al 25% del plan, con un mínimo de 10 solicitudes por minuto, y no reducen la capacidad de producción.
| Plan | Lecturas | Escrituras | Cotizaciones |
|---|---|---|---|
| Free | 60 | 30 | 20 |
| Growth | 300 | 150 | 60 |
| Scale | 1,000 | 500 | 200 |
| Enterprise | 5,000 | 2,500 | 1,000 |
07 / Guía
Conserva contexto útil sin registrar secretos
El error público puede incluir requestId. Guárdalo junto con la hora, método, ruta, estado HTTP y el identificador del recurso. Ese conjunto permite investigar una solicitud sin copiar el cuerpo completo ni una llave de API.
GET /v1/api-requests permite consultar el historial de la organización por modo, método, estado y periodo. Los resultados muestran metadatos como ruta, duración y requestId, pero no devuelven direcciones IP, agente de usuario ni valores de la consulta.
Sí registra: requestId, shipmentId, estado HTTP, error.code, ruta y hora.
No registra: X-API-Key, Authorization, Idempotency-Key completa ni datos personales del destinatario.
Una llave que consulta el historial necesita el alcance api_keys:read.
Separa los diagnósticos de TEST y LIVE igual que separas sus recursos.
08 / Guía
Fija la versión antes de depender de una respuesta
La versión vigente es 2026-05-01. Una organización queda fijada a una versión y las actualizaciones incompatibles se adoptan de forma explícita, por lo que tu contrato no debe cambiar por sorpresa.
Usa SendIt-Version en una solicitud de prueba para validar una versión antes de cambiar la configuración de la organización o de una llave. Ejecuta tu recorrido de cotización, compra, errores y webhooks antes de adoptar el cambio.
09 / Guía
Pon la confiabilidad dentro de tu salida a producción
Prueba estas decisiones con sk_test_ antes de conectar pedidos reales. Un camino exitoso demuestra el contrato básico; la salida a producción también necesita demostrar qué pasa cuando hay un límite, un dato inválido, una respuesta repetida y una compra incierta.
10 / Guía
Una API diseñada para operar, no solo para demostrar
SendIt ofrece el mismo contrato de errores, idempotencia, límites y versiones junto con las operaciones de cotización, guía y rastreo. El acceso completo a la API forma parte de todos los planes, incluido Free.
La plataforma está en pre-lanzamiento. Puedes usar el modo de prueba y sus $10,000 MXN virtuales para validar este comportamiento sin tarjeta y sin mezclarlo con una operación real.
Siguiente paso
Completa la tarea.
Preguntas frecuentes
Respuestas rápidas.
¿Idempotency-Key es obligatoria en la API de SendIt?
No. Es opcional en todas las mutaciones, pero se recomienda para compras de guía, anulaciones y otras operaciones que necesiten recuperarse de una interrupción de red sin repetir el efecto.
¿Debo cambiar la llave cuando una solicitud pierde la conexión?
No. Repite el mismo método, ruta, consulta y cuerpo con la misma llave. Cambiarla convertiría el reintento de transporte en una intención nueva.
¿Qué pasa si reutilizo una llave con otro cuerpo?
La API responde 409 IDEMPOTENCY_KEY_REUSED. Usa una llave nueva para una operación distinta y conserva la original para recuperar únicamente la solicitud que representa.
¿Cuánto tiempo conserva SendIt un resultado idempotente?
Durante 24 horas desde el primer uso. Un reintento idéntico dentro de ese periodo devuelve el estado y cuerpo almacenados, incluso cuando el resultado original fue una falla.
¿Cómo debo responder a un error 429?
Espera el número de segundos indicado por Retry-After y aplica una demora creciente si el límite continúa. No cambies de credencial para eludir la ventana.
¿Cómo investigo una compra cuyo resultado no conozco?
No abras otra compra. Conserva la misma llave y relaciona requestId, shipmentId, ruta y hora; consulta el recurso y el historial de solicitudes antes de escalar la conciliación.