Saltar al contenido principal
La API de Bold devuelve errores JSON siguiendo el formato de ProblemDetails. Algunos errores incluyen campos adicionales como code, parameters, requestId y traceId para facilitar diagnóstico.

​
Estructura

{
  "type": "https://api.bold-factory.com/errors/missing-permissions",
  "title": "Missing permissions",
  "status": 403,
  "detail": "Missing permissions: Items.Products.Read",
  "instance": "GET /v1/items/products",
  "code": "missing-permissions",
  "parameters": {
    "permissions": ["Items.Products.Read"]
  },
  "requestId": "0HN..."
}

​
Códigos HTTP habituales

CódigoSignificadoQué hacer
400 Bad RequestLa petición no tiene el formato esperado.Revisa tipos, campos obligatorios, fechas, rutas y parámetros de consulta.
401 UnauthorizedLa credencial no es válida.Comprueba Authorization o X-Api-Key.
403 ForbiddenFaltan permisos.Añade el permiso al rol o usa otra credencial.
404 Not FoundLa entidad no existe en la organización actual.Revisa id, reference, organización y entorno.
409 ConflictLa operación choca con entidades relacionadas o estado actual.Consulta dependencias antes de borrar o cambiar datos.
422 Unprocessable EntityLa petición es válida en formato, pero incumple una regla de negocio.Lee title, detail y parameters.
500 Internal Server ErrorError inesperado.Guarda requestId y contacta con soporte si persiste.

​
Cómo depurar

1

Lee el campo detail

El texto suele explicar la regla concreta que falló.
2

Busca parameters

Los parámetros indican cantidades, permisos, referencias o estados implicados.
3

Comprueba el estado de la entidad

Muchas operaciones quedan bloqueadas después de recibir, enviar, confirmar, iniciar o finalizar trabajo.
4

Guarda el identificador de petición

Incluye requestId o traceId cuando abras una incidencia.
Si recibes 403, la credencial existe y pertenece a una organización, pero no tiene al menos uno de los permisos exigidos. Revisa el perfil en Usuarios y permisos o crea una clave API con el alcance adecuado.
Si recibes 409 o 422, consulta el estado de la entidad. Por ejemplo, una recepción recibida, un envío expedido o una orden finalizada protegen parte de sus datos para conservar trazabilidad.