Common Standards & Errors

Este documento detalla los estándares globales, códigos de error y convenciones comunes aplicables a toda la API v1.

Headers Comunes

• Content-Type: application/json
• X-Pagination-Total-Count: Total de registros.
• X-Pagination-Page-Count: Total de páginas.
• X-Pagination-Current-Page: Página actual.
• X-Pagination-Per-Page: Registros por página.

Códigos de Error Globales

Error de Autenticación (401)

Ocurre cuando la API Key no es proporcionada o es inválida.

{
    "name": "Unauthorized",
    "message": "Your request was made with invalid credentials.",
    "code": 0,
    "status": 401
}

Acceso Prohibido (403)

Ocurre cuando el usuario autenticado no tiene permisos para la acción solicitada, o el servicio de la institución ha expirado.

{
    "name": "Forbidden",
    "message": "Acceso prohibido",
    "code": 0,
    "status": 403
}

Recurso No Encontrado (404)

Ocurre cuando el ID solicitado no existe o no tiene permisos.

{
    "name": "Not Found",
    "message": "Object not found: {id}",
    "code": 0,
    "status": 404
}

Error de Validación (422)

Ocurre cuando los datos enviados no cumplen con las reglas del modelo.

[
  {
    "field": "nombre_del_campo",
    "message": "Descripción del error."
  }
]

Error Interno (500)

Error inesperado en el servidor.

{
    "name": "Internal Server Error",
    "message": "An internal server error occurred.",
    "code": 0,
    "status": 500
}

Paginación y Filtrado

Consulte la Guía de Filtrado para todos los detalles sobre operadores simbólicos, sintaxis IN y ejemplos.

Paginación

Se controla mediante los parámetros:

• page: Número de página (1-based).
• per-page: Cantidad de elementos por página (Por defecto 20).

Ordenamiento

Parámetro sort:

• sort=campo: Ascendente.
• sort=-campo: Descendente.

Filtrado

Parámetro filter[campo]=valor:

• Soporta coincidencias exactas o parciales según el endpoint.
• Operadores de Comparación: Para campos de fecha y numéricos, se soportan operadores:
  • filter[campo][>]=valor: Mayor que (>)
  • filter[campo][>=]=valor: Mayor o igual que (>=)
  • filter[campo][<]=valor: Menor que (<)
  • filter[campo][<=]=valor: Menor o igual que (<=)
  • filter[campo][!=]=valor: No igual (!=)
  • filter[campo][=]=valor: Igual (=)
  • filter[campo][IN][]=valor1&filter[campo][IN][]=valor2: En el conjunto (IN)