Beartrack

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.

Token y Crear pedido
{
  "error": "invalid_token",
  "error_description": "El token no existe, venció o fue revocado."
}
Consultar pedido
{
  "message": "The package you are looking for does not exist.",
  "error": "Not Found",
  "statusCode": 404
}
Reacciona al código HTTP y, en la API para integradores, al campo 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.
400

Petición inválida

Petición incompleta o inválida

Pedir un token · Crear pedido

invalid_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 token

unsupported_grant_type

El único grant_type aceptado es client_credentials.

Solución. Envía grant_type=client_credentials.

Scope no permitido

Pedir un token

invalid_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.

401

No autorizado

Credenciales inválidas

Pedir un token

invalid_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

invalid_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

invalid_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.

403

Sin permiso

Scope insuficiente

Crear pedido

insufficient_scope

El token no tiene el scope que exige el endpoint (packages:write para crear pedidos).

Solución. Pide el token sin scope, o incluyendo el que exige el endpoint.

404

No encontrado

Pedido no encontrado

Consultar pedido

The 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.

429

Demasiadas peticiones

Demasiadas peticiones

Pedir un token · Crear pedido

too_many_requests

Superaste el límite de tu credencial: 10 canjes de token o 120 pedidos por minuto.

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.

502

Error de Beartrack

No se pudo crear el pedido

Crear pedido

server_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.

503

Servicio no disponible

Servicio no disponible

Pedir un token · Crear pedido

temporarily_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.