Errores

Todas las respuestas de error de la API REST de Content Island siguen un único contrato legible por máquina. El código HTTP y el campo error.code siempre coinciden, así que puedes ramificar por el que te resulte más cómodo en tu cliente.

Cuerpo de la respuesta

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Content \"abc123\" not found",
    "requestId": "0c3b1c64-3d4f-4f1f-9f4e-3f2c8b9a1e2d"
  }
}

• code — uno de los códigos listados más abajo. Identificador estable, seguro para usar en switch.
• message — descripción legible del fallo. Puede cambiar entre versiones; no la parsees.
• requestId — UUID generado por petición. El mismo valor aparece en los logs del servidor, así que puedes pasárselo a soporte para localizar un fallo concreto.
• details — información extra opcional, dependiente del código. Hoy aparece en VALIDATION_ERROR (ver abajo).

Códigos

Código	HTTP	Cuándo puedes verlo
VALIDATION_ERROR	400	Los query params o el body fallaron la validación. details.fields lo detalla.
UNAUTHORIZED	401	Token de acceso ausente, malformado o expirado.
FORBIDDEN	403	El token es válido pero no tiene permiso para la operación.
NOT_FOUND	404	El recurso solicitado no existe (o no es visible para este token).
CONFLICT	409	La petición entra en conflicto con el estado actual (p. ej. valor único duplicado).
RATE_LIMITED	429	Se superó el límite de peticiones a nivel de proyecto para un endpoint. Lo devuelve Exportar Proyecto (GET /api/1.0/project/export, limitado a 5 peticiones por proyecto cada 60 s).
INTERNAL_ERROR	500	Fallo inesperado del servidor. La respuesta nunca incluye stacks ni detalles internos — se registran en el servidor bajo requestId.

Nota

Una respuesta RATE_LIMITED (429) incluye una cabecera Retry-After con el número de segundos que quedan en la ventana actual antes de que se acepten nuevas peticiones. Consulta la guía de modo snapshot para el flujo de exportación.

Errores de validación

Cuando la petición falla la validación, la respuesta lleva un array details.fields describiendo cada fallo:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Validation failed. Please check the input values.",
    "requestId": "0c3b1c64-3d4f-4f1f-9f4e-3f2c8b9a1e2d",
    "details": {
      "fields": [
        { "field": "title", "message": "Required" },
        { "field": "slug", "message": "Must be unique" }
      ]
    }
  }
}

La forma de cada entrada es:

interface ValidationFieldError {
  field: string; // ruta con puntos o nombre del campo
  message: string; // legible, puede cambiar entre versiones
}

details se omite para errores que no necesitan contexto adicional (p. ej. UNAUTHORIZED, NOT_FOUND).

Correlación con soporte

Si necesitas reportar un fallo, incluye el valor requestId de la respuesta — nos permite localizar la petición exacta en nuestros logs.

Consejo

¿Estás usando el cliente JavaScript/TypeScript? Los errores lanzados por el cliente exponen requestId, code, status, message y details directamente en una ApiClientError tipada. Mira Manejo de errores para el patrón recomendado.

Garantías de estado

• El código HTTP siempre coincide con el code del body (p. ej. code: "NOT_FOUND" se sirve siempre como 404).
• Los fallos internos (500) nunca exponen stack traces, rutas internas ni mensajes de error de terceros. Se registran en el servidor, indexados por requestId.
• El body siempre se parsea como JSON cuando Content-Type es application/json. Otras respuestas (errores de gateway de la infraestructura por delante de la API, p. ej. una página HTML 502 de nginx) pueden no seguir este contrato — el cliente lo gestiona con un fallback (ver fallback).