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-11-04 · 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 de 60 peticiones por minuto por API key (429 con header retry-after) y una cuota mensual según tu plan (429 con el detalle del consumo: limit, currentUsage y remaining).
GET
/validateVerificar tu estado de cuota
Ante un 429 por cuota mensual, consulta /validate para conocer limit, currentUsage y remaining. Si el 429 es por rate limit, espera lo que indique el header retry-after antes de llamar de nuevo.
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. Hay dos 429 distintos y el cuerpo te dice cuál es. Si superaste el rate limit (60 peticiones por minuto), el cuerpo trae `"error": "Too Many Requests"` y el header `retry-after` indica cuántos segundos esperar. Si agotaste la cuota mensual del plan, el cuerpo trae `limit`, `currentUsage` y `remaining` en cero: reintentar no sirve hasta que se renueve el plan.
En ambos casos, espera un intervalo creciente entre intentos y reparte el trabajo en el tiempo. Los headers `x-ratelimit-limit` y `x-ratelimit-remaining` de cada respuesta te avisan antes de llegar al límite.
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 entre 8 y 12 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 (60 req/min por key; cuerpo { statusCode, error, message } y header retry-after) o cuota mensual agotada (cuerpo { error, 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?
60 peticiones por minuto por API key. Al superarlo la API responde 429 con el header retry-after, que indica cuánto esperar.
¿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