#Paginación y errores

#Paginación por cursor

Las listas públicas devuelven items, nextCursor y hasMore:

{
  "items": [],
  "nextCursor": "<opaque-cursor>",
  "hasMore": false
}

Cuando hasMore sea true, envía nextCursor sin modificarlo en el parámetro cursor de la petición siguiente. No decodifiques ni construyas cursores. El cursor queda ligado a los filtros y a la ordenación de la primera petición; si cambias alguno, inicia otra paginación sin cursor.

Las listas usan limit, con un valor predeterminado de 50 y un intervalo permitido de 1 a 200. El feed de cambios de productos usa pageSize con los mismos límites. Un cursor inválido devuelve 400 InvalidCursor. El feed puede devolver 410 ChangeCursorExpired cuando el punto solicitado ya no está en el historial conservado.

La mayoría de listas admite sort. Usa el nombre público del campo y antepón - para ordenar de forma descendente, por ejemplo sort=-modifiedAt. Una ordenación no admitida devuelve 400 InvalidSort.

#Formato de error

{
  "status": 403,
  "code": "forbidden",
  "message": "The bearer token does not grant the required scope.",
  "correlationId": "integracion-erp-0002",
  "currentConcurrencyToken": null
}

Los errores de validación pueden añadir validationErrors, agrupados por campo. Un conflicto de edición puede incluir currentConcurrencyToken. Las propiedades sin valor pueden omitirse según la respuesta. La API no expone trazas, nombres de excepciones, SQL ni detalles de Entity Framework.

Estados habituales:

• 400: petición o cursor incorrecto.
• 401: falta un token válido.
• 403: falta el scope requerido.
• 404: recurso inexistente.
• 409: conflicto con el estado actual.
• 422: regla de negocio incumplida.
• 429: límite temporal superado. Usa Retry-After.
• 500: error inesperado.

Envía un X-Correlation-ID distinto por operación, con un máximo de 128 caracteres. Trowel lo devuelve en la cabecera y en los errores para localizar la petición. Si no lo envías o no es válido, Trowel genera uno.