Ir al contenido
SShalom API

Errores y límites

Códigos de error de Shalom API Perú (400, 401, 403, 404, 409, 422, 429, 500, 502 y 503), el rate limit de 60 peticiones por minuto, la cuota mensual y cómo reintentar.

Los errores responden con un código HTTP y un cuerpo JSON con el campo error y, a veces, details o message. Las validaciones de formato responden 400 con message, que indica el campo con problemas. Los rechazos de Shalom (registro de guías, login) pueden llegar como { success: false, message }.

Tu error y el de origen no se tratan igual

Un 400, 401, 403 o 404 significan que la petición, la key o el dato están mal: reintentar no arregla nada. Un 429, 500, 502 o 503 sí se resuelven esperando y volviendo a intentar.

Un 409 en una operación Pro casi siempre es la sesión de la instancia: vuelve a iniciar sesión con POST /instances/login y reintenta.

Los errores 5xx pueden llegarte sin cuerpo JSON (por ejemplo, el texto "error code: 502"), porque el borde de la red los reemplaza. Trátalos por su código.

Qué hacer con un 429

Hay dos 429 distintos y el cuerpo te dice cuál es. Si superaste el rate limit de 60 peticiones por minuto, el cuerpo trae "error": "Too Many Requests" y el header retry-after indica cuántos segundos esperar. Los headers x-ratelimit-limit y x-ratelimit-remaining te avisan antes de llegar.

Si agotaste la cuota mensual del plan, el cuerpo trae limit, currentUsage y remaining en 0. Reintentar no sirve hasta el mes siguiente o hasta que mejores el plan. Los endpoints que no consumen cuota siguen funcionando.

En los dos casos, no reintentes en bucle: espera un intervalo creciente entre intentos y reparte el trabajo. Para seguir cambios de estado usa webhooks en lugar de consultar cada guía.

Vigila tu consumo antes de chocar

GET /validate devuelve el consumo del mes sin gastar cuota. Engánchalo a tu monitoreo y avisa a tu equipo cuando te acerques al límite, en lugar de descubrirlo con un 429 en producción.

Errores

CódigoSignificado
400Petición inválida: falta un campo, tiene otro tipo o está fuera de rango. También cuando Shalom rechaza un registro o una autogestión con su mensaje.
401Falta la API key o es inválida. En POST /instances/login, usuario o contraseña de Shalom Pro incorrectos.
403El plan venció, el plan no permite la acción (por ejemplo, crear más instancias), o el instanceId no pertenece a tu API key.
404El recurso no existe, por ejemplo una orden sin ose_id, una guía que no está en tus pendientes o una instancia inexistente.
409La instancia perdió la sesión de Shalom Pro y no pudo reconectarse, o Shalom no permite la operación en el estado actual de la guía.
422Shalom Pro no devolvió una tarifa para esa ruta (POST /account/quote).
429Rate limit superado (cuerpo { statusCode, error, message } y header retry-after) o cuota mensual agotada (cuerpo { error, limit, currentUsage, remaining: 0 }).
500Error interno o del sistema de Shalom sin un código más preciso. Reintenta con espera creciente.
502Shalom no respondió o devolvió un error. Reintenta en unos minutos.
503Un servicio de origen no está disponible, por ejemplo el cotizador público de Shalom (cotiza con instanceId).

Preguntas frecuentes

Relacionado