Saltar al contenido
Notificado
Menú
Crear cuenta

Errores

Cómo leer una negativa de Notificado (código, causa y solución) y los códigos que encontrará con más frecuencia.

Actualizado:

Toda negativa tiene las mismas tres partes:

Parte Qué es
code Estable, X_MAYUSCULAS. Decida con él, nunca con el texto.
cause Qué estaba mal, en palabras.
fix El siguiente paso que lo resuelve; normalmente literal.

En HTTP llegan como application/problem+json con status; en MCP, como resultado de herramienta con isError, o como respuesta HTTP (401, 413, 429) con el mismo cuerpo.

{
  "type": "urn:ultimate:error:X_CASE_RADICADO_TAKEN",
  "title": "case radicado taken",
  "status": 409,
  "code": "X_CASE_RADICADO_TAKEN",
  "cause": "this org already has open case <caseId> for radicado 05001310300320260012300",
  "fix": "use the existing case — getCase({ orgId, caseId: '<caseId>' }) — instead of opening a second one; to replace it with corrected data, createCase({ …, correctionOf: '<caseId>' }) archives it and opens the corrected case",
  "requestId": "<requestId>"
}

Cite el requestId cuando escriba a admin@notificado.co.

cause y fix vienen en inglés: son el texto que declara el propio sistema, el mismo que leen los asistentes de IA.

Las respuestas propias de la API (/v1)

Estado Código Qué hacer
401 X_UNAUTHENTICATED Sin token, o con uno desconocido, vencido o revocado. Emita uno nuevo en /cuenta/api.
404 X_ROUTE_NOT_FOUND La operación no existe o está fuera de los alcances del token. Revise la ruta y luego los alcances.
404 X_NOT_FOUND Una lectura de un objeto (get-case, get-notification, get-send-confirmation, get-import) no encontró ese identificador en su firma: no existe, es de otra firma o se borró. La operación sí existe y el token sí la alcanza. No reintente con el mismo identificador; búsquelo en el listado.
400 X_INPUT_INVALID También cuando un limit o un _first supera el máximo del listado: se rechaza, nunca se recorta. cause nombra el campo y el máximo; los máximos están en Límites. Pida menos filas y siga con nextCursor.
400 X_CURSOR_INVALID El cursor no es de este listado: viene de otro listado, de otros filtros u otro orden, se modificó, o la clave que lo firma cambió. También el cursor de exportNotifications con filtros distintos a los de la primera llamada. Pida de nuevo la primera página, sin cursor.
422 X_PAGE_LIMIT_INVALID Un tamaño de página fuera de sus límites llegó a la lectura misma. El esquema de cada operación suele detenerlo antes, con 400 X_INPUT_INVALID; las dos negativas significan lo mismo: nunca se recorta. Pida como máximo el tope que nombra cause y siga con el cursor.
422 X_DEADLINE_CURSOR_CONFLICT listDeadlines recibió cursor y after con valores distintos. after es el nombre anterior de cursor: envíe solo cursor.
409 X_IDEMPOTENCY_CONFLICT Ese Idempotency-Key nombra otro cuerpo, o su primer intento sigue en curso. Vea Reintentos idempotentes.
400 X_IDEMPOTENCY_KEY_INVALID Una clave vacía o de más de 255 caracteres.
429 X_RATE_LIMITED Superó el límite por token; espere Retry-After segundos.

Los dos 404 se distinguen por el código: X_ROUTE_NOT_FOUND habla de la operación, X_NOT_FOUND del objeto que pidió.

Cada código que la API puede responder, con su estado HTTP, qué significa y qué hacer, está en el catálogo de errores, cada uno con su ancla: /docs/api/errores#x-case-radicado-taken.

Códigos frecuentes

Código Qué hacer
X_INPUT_INVALID / X_BODY_INVALID Un campo no cumple el esquema; la lista de problemas nombra cada uno.
X_FORBIDDEN Su rol no permite la acción, o el orgId no es de su firma.
X_CSRF_BLOCKED Una escritura a las rutas del panel con cookie y sin origin. Nunca en /v1, que no recibe cookies; vea Autenticación.
X_KYC_REQUIRED Su verificación de abogado no está aprobada; complétela en el panel.
X_CASE_RADICADO_TAKEN El proceso ya existe; búsquelo en vez de crear otro.
X_CASE_RADICADO_INVALID El radicado no es un número de 23 dígitos válido.
X_NOTIFICATION_NOT_DRAFT La notificación ya se envió; no se puede editar ni reenviar.
X_NOTIFICATION_NO_RECIPIENTS Faltan destinatarios; agréguelos en el panel.
X_NOTIFICATION_NO_ATTACHMENTS Adjunte al menos un documento.
X_JURAMENTO_REQUIRED / X_PROVENANCE_REQUIRED Falta el juramento o la procedencia de una dirección.
X_ATTACHMENTS_TOO_LARGE Los adjuntos superan 6 MB en total. Comprima los PDF o repártalos en más de una notificación.
X_ATTACHMENT_DUPLICATE Ese documento ya está adjunto; puede continuar.
X_CREDITS_INSUFFICIENT No hay créditos suficientes. Con meta.mode = paid (la venta está habilitada desde el 30 de septiembre de 2026), compre un paquete en /creditos. Con meta.mode = free, la instalación no vende créditos: ya usó sus envíos gratuitos y puede escribir a admin@notificado.co (el equipo de Notificado puede asignarle créditos).
X_PAYMENT_CHECKOUT_DISABLED El pago en línea aún no está habilitado (modo gratuito); por ahora no se puede comprar. No reintente.
X_SEND_CONFIRMATION_EXPIRED Nadie confirmó el envío en 24 horas; no se envió nada.
X_SEND_CONFIRMATION_TOKEN_REVOKED El token o la conexión con que el agente pidió el envío se revocó antes de la confirmación; no se envió nada. Envíelo usted desde el borrador o pida al agente una nueva solicitud con una conexión vigente.
X_CONSTANCIA_NOT_FOUND Aún no hay constancia: se emite cuando llegan los eventos de entrega.
X_EVIDENCE_ZIP_NOT_READY El paquete se está armando; reintente una vez en 30 segundos.
X_MCP_SCOPE_DENIED El token no tiene el alcance de esa herramienta.
X_MCP_RATE_LIMITED Demasiadas llamadas; espere lo que indica retry-after.

Reintentos

No repita una llamada rechazada sin cambiarla. Solo se reintentan los *_NOT_READY, los límites de frecuencia y las fallas de red, después de esperar; una creación, con el mismo Idempotency-Key (Reintentos idempotentes).

Los asistentes tienen la misma lista, en inglés, en la guía docs://guides/errors del servidor MCP.