Los que vas a ver de verdad
401 cuando la API key falta o está mal enviada. 403 cuando el plan expiró o la función no está incluida. 404 cuando la guía, el DNI o la ruta no existen. Y 429 cuando te pasas del límite.
Errores y límites
Última actualización: 2026-09-21 · Base URL: https://api.shalom-api.lat
Todos los errores devuelven JSON con la forma { "error": "mensaje", "details": "opcional", "message": "opcional" } y el código HTTP correcto. La plataforma aplica un rate limit global de 1000 peticiones por minuto y una cuota mensual según tu plan: cuando la superas recibes 429 con el detalle del consumo.
GET
/validateVerificar tu estado de cuota
Ante un 429, consulta /validate para conocer limit, currentUsage y remaining antes de reintentar.
curl -X GET "https://api.shalom-api.lat/validate" \
-H "x-api-key: TU_API_KEY"Respuesta (ejemplo)
{
"valid": true,
"userId": "b7c9d1e2-4f6a-4c3b-9d2e-1a2b3c4d5e6f",
"limit": 1000,
"currentUsage": 998,
"remaining": 2,
"message": "API key válida"
}Tu error y el suyo no se tratan igual
Un 400 o un 404 significan que la petición o el dato están mal: reintentar no arregla nada, hay que corregir lo que envías. Un 429 o un 500 sí se resuelven esperando y volviendo a intentar.
Qué hacer con un 429
No reintentes en bucle. El cuerpo trae `limit`, `currentUsage` y `remaining` en cero, así que sabes exactamente dónde estás. Espera un intervalo creciente entre intentos y reparte el trabajo en el tiempo.
Qué hacer con un 500
Es un error interno o del sistema origen, no de tu integración. Reintenta con backoff exponencial; si persiste, conviene mirar el estado del servicio antes de seguir insistiendo.
Vigila tu consumo antes de chocar
GET /validate devuelve el estado de tu key y el consumo del mes. Engánchalo a tu monitorización y avisa a tu equipo cuando te acerques al límite, en lugar de descubrirlo con un 429 en producción.
Errores de esta sección
| 400 | Petición malformada: falta un campo, el orderNumber no tiene 8 dígitos, etc. |
| 401 | Sin autenticación o API key inválida. |
| 403 | Sin permisos: plan expirado o funcionalidad no incluida en tu plan. |
| 404 | Recurso no encontrado: guía inexistente, DNI desconocido, ruta mal escrita. |
| 429 | Rate limit (1000 req/min) o cuota mensual agotada. Cuerpo: { limit, currentUsage, remaining: 0 }. |
| 500 | Error interno o del sistema origen. Reintenta con backoff exponencial. |
Preguntas frecuentes
¿Qué significa un error 403 en Shalom API?
Sin permisos: el plan expiró o la funcionalidad no está incluida en tu plan.
¿Cómo sé cuánta cuota me queda este mes?
Con GET /validate, que devuelve el estado de la key y el consumo del mes.
¿Debo reintentar un 404?
No. Significa que el recurso no existe: la guía, el DNI o la ruta están mal escritos.
¿Cuál es el límite de peticiones?
1000 peticiones por minuto. Al superarlo la API responde 429 con el detalle de tu consumo.
¿Qué hago si recibo un 500?
Reintentar con backoff exponencial. Es un error interno o del sistema origen, no de tu integración.
Continúa con
¿Aún no tienes API key?
Escríbenos por WhatsApp y la recibes de inmediato para probar todos estos ejemplos.
Solicitar API key