Errores

Todo error de la API de Driftless (ya sea que lo alcances por la CLI, el servidor MCP o directamente) vuelve como el mismo sobre JSON. Un agente debería ramificar según el code legible por máquina, no parsear el message humano.

El sobre

{
  "statusCode": 403,
  "code": "MISSING_HUMAN_IDENTITY",
  "message": "Merging into Knowledge requires owner/admin authority: your own session or an owned owner/admin key (an agent acting on your explicit request). A faceless agent (ownerless key / OAuth) cannot merge.",
  "request_id": "a1b2c3d4",
  "retryable": false,
  "endpoint": "POST /api/v1/workspaces/acme/topics/auth-flow/approve"
}

Campo	Significado
`statusCode`	Estado HTTP.
`code`	Código de error estable y legible por máquina (esta lista es solo aditiva).
`message`	Legible por humanos, accionable. Te dice cómo arreglarlo. Puede cambiar; no hagas match sobre él.
`request_id`	Id de correlación. Cítalo al reportar un problema.
`retryable`	`true` solo para fallos transitorios genuinos (5xx). Un `4xx` es una respuesta definitiva, así que reintentar no ayuda.
`endpoint`	El método + la ruta que produjo el error.

retryable es honesto: la CLI reintenta un GET una vez ante un fallo transitorio, pero nunca reenvía una escritura, y nunca reintenta un 4xx. Si construyes tu propio cliente, haz lo mismo.

Por qué un `code` siquiera

Una entrada incorrecta no debería llegar al agente como un 500 opaco. Dos capas lo garantizan:

La validación rechaza un enum inválido (status, visibility) con un 400 a nivel de campo antes de que toque la base de datos.
Un traductor de errores de Postgres captura cualquier violación de restricción que se escape y la convierte en un 4xx codificado, nunca en un 500 genérico.

Después de esas dos, un 500 significa lo que debe: un bug real o una caída. Ese es también el único momento en que retryable es true.

Catálogo de códigos

Validación y entrada

`code`	Estado	Cuándo
`VALIDATION_FAILED`	422 / 400	Un campo del cuerpo de la petición falló la validación (p. ej. `status must be one of: draft, proposed, reviewed, …`).
`BAD_REQUEST`	400	Una petición inválida genérica sin un código más específico.
`INVALID_VALUE`	400	Un valor viola una restricción CHECK de la base de datos.
`INVALID_ID`	400	Un identificador de ruta/cuerpo no es un UUID válido.
`REQUIRED_FIELD`	400	Faltaba un campo requerido.
`FK_VIOLATION`	400	Referencia un registro que no existe.
`SECRET_DETECTED`	400	Un campo de topic parecía una credencial (API key, token, clave privada) y la escritura se bloqueó. Quítala, o define `allow_secrets: true` (CLI `--allow-secrets`) para forzarla. El error enmascara la coincidencia; nunca repite el secreto.

Acceso e identidad

`code`	Estado	Cuándo
`UNAUTHORIZED`	401	API key / token faltante o inválido. → `driftless login --key <key>`.
`FORBIDDEN`	403	Autenticado, pero sin permiso.
`MISSING_HUMAN_IDENTITY`	403	Un principal sin rostro (una key sin dueño, o un token OAuth sin un owner/admin detrás) intentó fusionar en Knowledge. Vuelve a emitir la key desde el dashboard para que lleve tu identidad, o ejecuta la fusión bajo un owner/admin.
`INSUFFICIENT_ROLE`	403	No tienes el rol de workspace para esta acción: solo un owner/admin puede aprobar. Pídele a uno que te promueva en Settings → Members.
`NOT_FOUND`	404	El recurso no existe (o es el borrador privado de otro miembro que no puedes ver, así que devolvemos 404, nunca 403).
`METHOD_NOT_ALLOWED`	405	La ruta es real pero el verbo no — lleva un header `Allow` compatible con RFC 9110 que nombra los métodos que sí funcionan. La superficie HTTP de Market Data devuelve esto en vez de un 404 desnudo ante una petición con el verbo equivocado.

Gobernanza y conflictos

`code`	Estado	Cuándo
`DUPLICATE`	409	Ya existe un registro con estos valores.
`DUPLICATE_TOPIC`	409	Ya existe un topic con ese slug en el workspace.
`VERSION_CONFLICT`	409	`expected_version` no coincidió: alguien escribió desde que leíste. Vuelve a leer y reintenta.
`CONFLICT`	409	Un conflicto de estado genérico.
`PROTECTED_RESOURCE`	403	Un recurso protegido/por defecto no puede modificarse ni eliminarse.
`RATE_LIMITED`	429	Demasiadas peticiones. Reduce el ritmo.

Saldo comercial

`code`	Estado	Cuándo
`COMMERCIAL_CALL_LIMIT_REACHED`	402	El workspace agotó sus solicitudes comerciales de primer nivel del mes.
`COMMERCIAL_CREDITS_EXHAUSTED`	402	No quedan créditos de inteligencia comercial en el mes actual.
`COMMERCIAL_CREDITS_INSUFFICIENT`	402	La cantidad de resultados solicitada supera el máximo por solicitud o el saldo restante.

Estos errores incluyen el estado actual en usage y una next_action accionable para hablar con ventas. Son definitivos (retryable: false).

Servidor

`code`	Estado	Cuándo
`INTERNAL`	500	Un fallo inesperado. `retryable: true`. Cita `request_id` si persiste.

Observabilidad

Cada error capturado también se emite a PostHog (request_failed del lado del servidor, command_failed desde la CLI) con code, status_code y endpoint como propiedades, de modo que la superficie de errores es un único mapa consultable, segmentable por tipo y endpoint en vez de texto libre. El texto de la excepción nunca sale del log — se une por request_id.

Primeros pasos

Conectar

Conceptos

Trabajar y colaborar

Guías

Agentes

Referencia MCP

Referencia CLI

Referencia API

Plataforma

El sobre

Por qué un `code` siquiera

Catálogo de códigos

Validación y entrada

Acceso e identidad

Gobernanza y conflictos

Saldo comercial

Servidor

Observabilidad

​El sobre

​Por qué un code siquiera

​Catálogo de códigos

​Validación y entrada

​Acceso e identidad

​Gobernanza y conflictos

​Saldo comercial

​Servidor

​Observabilidad

El sobre

Por qué un `code` siquiera

Catálogo de códigos

Validación y entrada

Acceso e identidad

Gobernanza y conflictos

Saldo comercial

Servidor

Observabilidad