Errores - Clausum

Clausum usa códigos de estado HTTP convencionales. 2xx éxito, 4xx error del cliente, 5xx error del servidor o disponibilidad.

Códigos de estado

Status	Significado
`200`	Éxito
`201`	Recurso creado
`400`	Error de validación
`401`	No autorizado — credencial ausente, inválida, deshabilitada o revocada
`403`	Prohibido — tipo de clave incorrecto o permiso faltante
`404`	No encontrado
`409`	Conflicto — recurso duplicado
`429`	Límite de tasa excedido
`500`	Error interno del servidor
`503`	Servicio no disponible — mantenimiento de assess
`504`	Timeout de gateway — timeout de assess

Forma del error

Los endpoints partner y de gestión devuelven un objeto estructurado:

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "currency must be a 3-letter ISO code",
    "details": {}
  }
}

Ramifica por error.code. En 429, respeta X-RateLimit-Reset y reintenta con backoff.

Códigos partner assess

Código	HTTP	Acción
`ASSESS_MAINTENANCE`	`503`	Fail-open a revisión manual o encolar pago — consulta Resiliencia de assess
`ASSESS_TIMEOUT`	`504`	Reintenta con el mismo `order_id` / `Idempotency-Key` (backoff exponencial)
`VALIDATION_ERROR`	`400`	Corrige payload — consulta catálogo de campos `GET /api/v1/assess`
`SECRET_KEY_REQUIRED`	`401`	Usa `clm_sk_*` (p. ej. payout requiere clave secret)
`PUBLIC_KEY_NOT_ALLOWED`	`403`	El endpoint requiere clave secret
`RATE_LIMIT_EXCEEDED`	`429`	Retrocede y reintenta

Códigos comunes de gestión

Código	Causa típica
`UNAUTHORIZED`	Sin JWT / clave o JWT / clave inválida
`FORBIDDEN`	El rol carece de permiso
`INVALID_TYPE`	`list_type` no soportado
`DUPLICATE`	La entrada de blocklist ya existe
`NOT_FOUND`	Recurso ausente

Manejo de errores

const res = await fetch(url, options)

if (!res.ok) {
  const body = await res.json().catch(() => ({}))
  const err = body.error
  const code = typeof err === "object" ? err?.code : undefined
  const message = typeof err === "string" ? err : err?.message

  if (res.status === 503 && code === "ASSESS_MAINTENANCE") {
    return yourFailOpenPolicy()
  }
  if (res.status === 504 && code === "ASSESS_TIMEOUT") {
    return retryWithSameIdempotencyKey()
  }
  if (res.status === 429) return retryWithBackoff()

  throw new ClausumError(code, message)
}

Reintenta 5xx, 503, 504 y 429. Para otros 4xx, corrige la solicitud antes de reintentar.