Errores y límites de tasa

Cuando una solicitud a la API falla, ShipSaving devuelve una respuesta de error estructurada con un code legible por máquina y un msg amigable para humanos. Esta página documenta el formato de las respuestas de error, los códigos de estado HTTP y los límites de tasa.

Formato de la respuesta de error

Todas las respuestas de la API, incluidos los errores, comparten la misma estructura JSON:

Respuesta de éxito:

{
  "code": "ok",
  "msg": "ok",
  "data": { ... }
}

Respuesta de error:

{
  "code": "shipment.address.city_can_not_be_null",
  "msg": "City is required.",
  "data": null
}

Campo	Tipo	Descripción
`code`	string	`"ok"` en caso de éxito; un código de error separado por puntos en caso de fallo (por ejemplo, `shipment.buy.pay_shipment_failed`).
`msg`	string	Un mensaje legible por humanos que describe el resultado.
`data`	object / null	La carga útil de la respuesta en caso de éxito; `null` en caso de fallo.

Códigos de estado HTTP

Código	Significado	Cuándo ocurre
200	OK	La solicitud se completó con éxito. Revisa el campo `code`: `"ok"` significa éxito.
400	Bad Request	La solicitud contiene parámetros inválidos, campos obligatorios faltantes o una violación de la lógica de negocio. El campo `code` contiene un código de error específico.
401	Unauthorized	El token de acceso falta, está expirado o es inválido. Obtén un nuevo token mediante `/oauth2/token`.
429	Demasiadas solicitudes	Has excedido el límite de solicitudes.
500	Internal Server Error	Ocurrió un error inesperado de nuestro lado. Si persiste, contacta a soporte.

Convención de códigos de error

Los códigos de error siguen un patrón de nombres separados por puntos que indica el dominio y el problema específico:

{domain}.{subdomain}.{detail}

Por ejemplo:

shipment.address.city_can_not_be_null — Dominio shipment → Subdominio address → Ciudad faltante
common.transaction.wallet_balance_not_enough — Dominio common → Subdominio transaction → Saldo insuficiente

Este patrón te ayuda a categorizar los errores programáticamente en tu integración.

Excepción

El endpoint /oauth2/token sigue el formato de error de OAuth 2.0 y no usa la convención de puntos descrita arriba. Consulta Autenticación para más detalles.

Límites de tasa

Los límites de tasa se aplican en tres niveles:

Nivel	Alcance	Descripción
App Key	Por API key	Cada `app_key` tiene su propia cuota. Una integración con mucho tráfico no afectará a tus otras claves.
Company	Por cuenta	Todas las API keys bajo la misma compañía comparten un límite combinado, incluso si usas varias claves.
Global	A nivel de plataforma	Un tope general en todo el sistema, aplicado a todos los usuarios. Si la plataforma está bajo carga elevada, las solicitudes pueden ser rechazadas aunque tu clave tenga capacidad disponible.

Una solicitud debe pasar todos los niveles aplicables. Si se excede cualquiera de ellos, la solicitud se rechaza.

Los límites pueden variar

Los límites varían según el endpoint y el nivel de cuenta, y pueden cambiar con el tiempo. Si necesitas mayor rendimiento, contacta a tu gerente de cuenta.

Cuando excedes el límite, la API devuelve HTTP 429 con el código de error common.check.rate_limit:

{
  "code": "common.check.rate_limit",
  "msg": "request too frequent",
  "data": null
}

Recomendaciones de manejo

Revisa el campo code, no solo el estado HTTP.
Una respuesta 200 con "code": "error" sigue siendo un error. Verifica siempre code == "ok" antes de procesar data.
Maneja los errores de autenticación con cuidado.
Existen dos tipos de errores 401:

Credenciales inválidas: si /oauth2/token devuelve 401 con {"error": "invalid_client"}, tu app_key o app_secret es incorrecto. Verifica tus credenciales, no reintentes.
Token de acceso expirado: si cualquier otro endpoint de la API devuelve 401 con un cuerpo vacío, tu token de acceso ha expirado. Solicita un nuevo token a /oauth2/token y reintenta la solicitud original.

Implementa reintentos con backoff para errores transitorios.
Para errores como common.redis_lock.system_busy, shipment.pay.get_pay_lock_failed o common.check.rate_limit, reintenta con backoff exponencial:
```
Espera 1s → reintenta → espera 2s → reintenta → espera 4s → reintenta → desiste
```
No reintentes errores de validación.
Los errores en las categorías shipment.address.*, shipment.package.* y shipment.custom.* indican entrada inválida. Corrige los parámetros de la solicitud antes de reintentar.
Usa platform_uk_id para evitar envíos duplicados.
Si recibes un timeout o una respuesta ambigua durante la compra de la etiqueta, consulta el estado del envío antes de reintentar. El error shipment.current_platform_uk_id_already_create_shipment protege contra cargos duplicados.