Recursos
Errores
Cada causa que la API declara, qué la provoca y cómo resolverla.
Formato
Los errores llegan como JSON, con dos formas según el endpoint.
{
"error": "invalid_token",
"error_description": "El token no existe, venció o fue revocado."
}{
"message": "The package you are looking for does not exist.",
"error": "Not Found",
"statusCode": 404
}error: los dos son estables. error_description y message están pensados para tus logs, no para mostrárselos al cliente final: su texto puede cambiar.Petición inválida
Petición incompleta o inválida
Pedir un token · Crear pedido · Consultar pedido · Buscar por order_id · Cancelar pedidoinvalid_request
Falta un dato obligatorio —la cabecera Authorization, grant_type en el token o un campo del pedido como order_id— o el cuerpo no pasó la validación. error_description dice qué falló.
Solución. Corrige la petición según error_description. Reintentarla igual no cambia el resultado.
Grant no soportado
Pedir un tokenunsupported_grant_type
El único grant_type aceptado es client_credentials.
Solución. Envía grant_type=client_credentials.
Scope no permitido
Pedir un tokeninvalid_scope
Pediste un scope que la credencial no tiene.
Solución. Omite scope para recibir todos los de la credencial, o pide solo los que tiene.
No autorizado
Credenciales inválidas
Pedir un tokeninvalid_client
El client_id no existe, el client_secret no corresponde o la credencial fue revocada. Por seguridad, la respuesta es la misma en los tres casos.
Solución. Revisa la credencial en el portal. Si rotaste el secreto, usa el nuevo; si la revocaste, crea otra. Usa un solo método: Basic o client_id y client_secret en el cuerpo.
Petición incompleta o inválida
Crear pedido · Consultar pedido · Buscar por order_id · Cancelar pedidoinvalid_request
Falta un dato obligatorio —la cabecera Authorization, grant_type en el token o un campo del pedido como order_id— o el cuerpo no pasó la validación. error_description dice qué falló.
Solución. Corrige la petición según error_description. Reintentarla igual no cambia el resultado.
Token inválido o vencido
Crear pedido · Consultar pedido · Buscar por order_id · Cancelar pedidoinvalid_token
El token no existe, venció (dura una hora) o la credencial se rotó o revocó después de emitirlo.
Solución. Pide un token nuevo y reintenta una vez. Si vuelve a fallar, revisa la credencial en el portal.
Sin permiso
Scope insuficiente
Crear pedido · Consultar pedido · Buscar por order_id · Cancelar pedidoinsufficient_scope
El token no tiene el scope que exige el endpoint: packages:write para crear y cancelar, packages:read para consultar.
Solución. Pide el token sin scope, o incluyendo el que exige el endpoint.
No encontrado
Pedido no encontrado
Consultar pedido · Cancelar pedidonot_found
No hay un pedido con ese número de seguimiento en tu comercio. Un pedido de otro comercio responde igual que uno inexistente.
Solución. Confirma el número: es el following_number que devolvió Crear pedido, no tu order_id (para ese usa Buscar por order_id).
Pedido no encontrado
Seguimiento públicoThe package you are looking for does not exist.
No hay ningún paquete con ese número de seguimiento.
Solución. Confirma el followingNumber. Tras crear un pedido, usa el following_number que devuelve la respuesta, no el order_id de tu tienda.
Conflicto
El pedido ya no se puede cancelar
Cancelar pedidoinvalid_state
El operador ya retiró el pedido: solo se cancela en los estados 0 y 100. error_description dice en qué estado está.
Solución. No reintentes: el resultado no cambia. Coordina la anulación con tu operador.
Demasiadas peticiones
Demasiadas peticiones
Pedir un token · Crear pedido · Consultar pedido · Buscar por order_id · Cancelar pedidotoo_many_requests
Superaste el límite de tu credencial, por minuto: 10 canjes de token, 120 pedidos, 300 consultas o 60 cancelaciones. Cada límite es independiente.
Solución. No envíes más peticiones hasta que pasen al menos los segundos que indica la cabecera Retry-After: las rechazadas también cuentan para el límite. Si vuelve a responder 429, espera un minuto completo. Y reutiliza el token durante su hora de vida en vez de pedir uno por petición.
Error de Beartrack
No se pudo crear el pedido
Crear pedidoserver_error
Falló algo del lado de Beartrack al registrar el pedido.
Solución. Reintenta con backoff, el mismo order_id y los mismos datos: dentro de 24 horas no se duplica. Si persiste, escríbenos con el x-correlation-id de la respuesta.
Servicio no disponible
Servicio no disponible
Pedir un token · Crear pedido · Consultar pedido · Buscar por order_id · Cancelar pedidotemporarily_unavailable
Beartrack no pudo procesar la petición en este momento.
Solución. Reintenta con backoff exponencial. En pedidos, con el mismo order_id, los mismos datos y dentro de 24 horas.