Paginación y errores

Todo endpoint de lista pagina del mismo modo y toda respuesta no-2xx envuelve el mismo envelope. Esta página documenta esas convenciones compartidas para que las páginas por-recurso se centren en los campos específicos del recurso.

Paginación

Los endpoints de lista usan un índice de página 1-based más un tamaño de página:

La respuesta envuelve el envelope estándar {rows, pagination}:

{
  "data": {
    "rows": [
      { "id": 12, "name": "..." },
      { "id": 13, "name": "..." }
    ],
    "pagination": {
      "page": 1,
      "pageSize": 500,
      "total": 18,
      "totalPages": 1
    }
  }
}

Para iterar por todas las filas, incrementa page hasta que page > totalPages.

Envelope de respuesta

Cada respuesta de la API — éxito y fallo por igual — envuelve su payload en un envelope estándar. En éxito, el recurso (o el envelope de lista anterior) va bajo data. En fallo, el envelope lleva el código de error, el mensaje legible y el request id.

{
  "success": false,
  "code": "APIf006",
  "message": "Field username exceeds the maximum length of 30 characters.",
  "data": ["username", 30],
  "request_id": "<request-id>"
}

Catálogo de errores

La plataforma expone un catálogo de errores estable basado en prefijos. Los códigos los publica el servidor en el mismo deploy y son estables entre versiones — consulta el spec OpenAPI para la referencia exacta por operación.

Discrimina por code para manejo grueso; consulta las páginas por-recurso para los códigos que una operación dada puede producir. Los códigos heredados con prefijo en mayúsculas (APIF517, APIF519, SYSF008) siguen circulando en respuestas legacy y son equivalentes a la familia en minúsculas.

Códigos HTTP

Request id

Cada respuesta incluye X-Request-Id y replica el mismo valor en request_id en fallos. Los Operators incluyen este id en los tickets de soporte para que el equipo de plataforma pueda recuperar el log servidor correspondiente.

X-Request-Id: <request-id>

Guía de reintentos

Reintenta solo en fallos transitorios:

Cuando reintentes mutaciones, envía el mismo Idempotency-Key para que el servidor pueda deduplicar. Consulta API Overview para el contrato de idempotencia.

FAQ