> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clausum.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Errores

> Códigos de estado HTTP y formas de respuesta de error

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:

```json theme={null}
{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "currency must be a 3-letter ISO code",
    "details": {}
  }
}
```

<Tip>
  Ramifica por `error.code`. En **429**, respeta `X-RateLimit-Reset` y reintenta con backoff.
</Tip>

## 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](/es/guides/assess-resilience) |
| `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

```ts theme={null}
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)
}
```

<Note>
  Reintenta `5xx`, `503`, `504` y `429`. Para otros `4xx`, corrige la solicitud antes de reintentar.
</Note>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.