{"templateId":"markdown","sharedDataIds":{"sidebar":"sidebar-@l10n/es/v2/sidebars.yaml"},"props":{"metadata":{"markdoc":{"tagList":["admonition"]},"type":"markdown"},"seo":{"title":"Errores y límites de tasa"},"dynamicMarkdocComponents":[],"compilationErrors":[],"ast":{"$$mdtype":"Tag","name":"article","attributes":{},"children":[{"$$mdtype":"Tag","name":"Heading","attributes":{"level":2,"id":"errores-y-límites-de-tasa","__idx":0},"children":["Errores y límites de tasa"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cuando una solicitud a la API falla, ShipSaving devuelve una respuesta de error estructurada con un ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," legible por máquina y un ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["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."]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"formato-de-la-respuesta-de-error","__idx":1},"children":["Formato de la respuesta de error"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Todas las respuestas de la API, incluidos los errores, comparten la misma estructura JSON:"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respuesta de éxito:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"ok\",\n  \"msg\": \"ok\",\n  \"data\": { ... }\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Respuesta de error:"]}]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"shipment.address.city_can_not_be_null\",\n  \"msg\": \"City is required.\",\n  \"data\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Campo"},"children":["Campo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Tipo"},"children":["Tipo"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descripción"},"children":["Descripción"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ok\""]}," en caso de éxito; un código de error separado por puntos en caso de fallo (por ejemplo, ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.buy.pay_shipment_failed"]},")."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["msg"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["string"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Un mensaje legible por humanos que describe el resultado."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["object / null"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["La carga útil de la respuesta en caso de éxito; ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["null"]}," en caso de fallo."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"códigos-de-estado-http","__idx":2},"children":["Códigos de estado HTTP"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Código"},"children":["Código"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Significado"},"children":["Significado"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Cuándo ocurre"},"children":["Cuándo ocurre"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["200"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["OK"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["La solicitud se completó con éxito. Revisa el campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},": ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"ok\""]}," significa éxito."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["400"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Bad Request"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["La solicitud contiene parámetros inválidos, campos obligatorios faltantes o una violación de la lógica de negocio. El campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]}," contiene un código de error específico."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["401"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Unauthorized"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["El token de acceso falta, está expirado o es inválido. Obtén un nuevo token mediante ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]},"."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["429"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Demasiadas solicitudes"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Has excedido el límite de solicitudes."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["500"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Internal Server Error"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Ocurrió un error inesperado de nuestro lado. Si persiste, contacta a soporte."]}]}]}]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"convención-de-códigos-de-error","__idx":3},"children":["Convención de códigos de error"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Los códigos de error siguen un ",{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["patrón de nombres separados por puntos"]}," que indica el dominio y el problema específico:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"{domain}.{subdomain}.{detail}\n"},"children":[]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Por ejemplo:"]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.address.city_can_not_be_null"]}," — Dominio shipment → Subdominio address → Ciudad faltante"]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.transaction.wallet_balance_not_enough"]}," — Dominio common → Subdominio transaction → Saldo insuficiente"]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Este patrón te ayuda a categorizar los errores programáticamente en tu integración."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Excepción"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["El endpoint ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," sigue el ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"https://datatracker.ietf.org/doc/html/rfc6749#section-5.2"},"children":["formato de error de OAuth 2.0"]}," y no usa la convención de puntos descrita arriba. Consulta ",{"$$mdtype":"Tag","name":"MarkdownLink","attributes":{"href":"/es/v2/authentication"},"children":["Autenticación"]}," para más detalles."]}]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"límites-de-tasa","__idx":4},"children":["Límites de tasa"]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Los límites de tasa se aplican en tres niveles:"]},{"$$mdtype":"Tag","name":"div","attributes":{"className":"md-table-wrapper"},"children":[{"$$mdtype":"Tag","name":"table","attributes":{"className":"md"},"children":[{"$$mdtype":"Tag","name":"thead","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Nivel"},"children":["Nivel"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Alcance"},"children":["Alcance"]},{"$$mdtype":"Tag","name":"th","attributes":{"data-label":"Descripción"},"children":["Descripción"]}]}]},{"$$mdtype":"Tag","name":"tbody","attributes":{},"children":[{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["App Key"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Por API key"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Cada ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}," tiene su propia cuota. Una integración con mucho tráfico no afectará a tus otras claves."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Company"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Por cuenta"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["Todas las API keys bajo la misma compañía comparten un límite combinado, incluso si usas varias claves."]}]},{"$$mdtype":"Tag","name":"tr","attributes":{},"children":[{"$$mdtype":"Tag","name":"td","attributes":{},"children":[{"$$mdtype":"Tag","name":"strong","attributes":{},"children":["Global"]}]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["A nivel de plataforma"]},{"$$mdtype":"Tag","name":"td","attributes":{},"children":["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."]}]}]}]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Una solicitud debe pasar todos los niveles aplicables. Si se excede cualquiera de ellos, la solicitud se rechaza."]},{"$$mdtype":"Tag","name":"Admonition","attributes":{"type":"info","name":"Los límites pueden variar"},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["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."]}]},{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Cuando excedes el límite, la API devuelve HTTP ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["429"]}," con el código de error ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.check.rate_limit"]},":"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"data-language":"json","header":{"controls":{"copy":{}}},"source":"{\n  \"code\": \"common.check.rate_limit\",\n  \"msg\": \"request too frequent\",\n  \"data\": null\n}\n","lang":"json"},"children":[]},{"$$mdtype":"Tag","name":"hr","attributes":{},"children":[]},{"$$mdtype":"Tag","name":"Heading","attributes":{"level":3,"id":"recomendaciones-de-manejo","__idx":5},"children":["Recomendaciones de manejo"]},{"$$mdtype":"Tag","name":"ol","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Revisa el campo ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code"]},", no solo el estado HTTP.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Una respuesta ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["200"]}," con ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["\"code\": \"error\""]}," sigue siendo un error. Verifica siempre ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["code == \"ok\""]}," antes de procesar ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["data"]},"."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Maneja los errores de autenticación con cuidado.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Existen dos tipos de errores ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]},":"]}]}]},{"$$mdtype":"Tag","name":"ul","attributes":{},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Credenciales inválidas: si ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," devuelve ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," con ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["{\"error\": \"invalid_client\"}"]},", tu ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_key"]}," o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["app_secret"]}," es incorrecto. Verifica tus credenciales, no reintentes."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Token de acceso expirado: si cualquier otro endpoint de la API devuelve ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["401"]}," con un cuerpo vacío, tu token de acceso ha expirado. Solicita un nuevo token a ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["/oauth2/token"]}," y reintenta la solicitud original."]}]}]},{"$$mdtype":"Tag","name":"ol","attributes":{"start":3},"children":[{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Implementa reintentos con backoff para errores transitorios.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Para errores como ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.redis_lock.system_busy"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.pay.get_pay_lock_failed"]}," o ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["common.check.rate_limit"]},", reintenta con backoff exponencial:"]},{"$$mdtype":"Tag","name":"CodeBlock","attributes":{"header":{"controls":{"copy":{}}},"source":"Espera 1s → reintenta → espera 2s → reintenta → espera 4s → reintenta → desiste\n"},"children":[]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["No reintentes errores de validación.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"Los errores en las categorías ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.address.*"]},", ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.package.*"]}," y ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.custom.*"]}," indican entrada inválida. Corrige los parámetros de la solicitud antes de reintentar."]}]},{"$$mdtype":"Tag","name":"li","attributes":{},"children":[{"$$mdtype":"Tag","name":"p","attributes":{},"children":["Usa ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["platform_uk_id"]}," para evitar envíos duplicados.",{"$$mdtype":"Tag","name":"br","attributes":{},"children":[]},"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 ",{"$$mdtype":"Tag","name":"code","attributes":{},"children":["shipment.current_platform_uk_id_already_create_shipment"]}," protege contra cargos duplicados."]}]}]}]},"headings":[{"value":"Errores y límites de tasa","id":"errores-y-límites-de-tasa","depth":2},{"value":"Formato de la respuesta de error","id":"formato-de-la-respuesta-de-error","depth":3},{"value":"Códigos de estado HTTP","id":"códigos-de-estado-http","depth":3},{"value":"Convención de códigos de error","id":"convención-de-códigos-de-error","depth":3},{"value":"Límites de tasa","id":"límites-de-tasa","depth":3},{"value":"Recomendaciones de manejo","id":"recomendaciones-de-manejo","depth":3}],"frontmatter":{"seo":{"title":"Errores y límites de tasa"}},"lastModified":"2026-08-26T18:17:57.000Z","pagePropGetterError":{"message":"","name":""}},"slug":"/es/v2/errors","userData":{"isAuthenticated":false,"teams":["anonymous"]},"isPublic":true}