Referencia
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.
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 con cookie sin origin; 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 20 MB en total. |
X_ATTACHMENT_DUPLICATE |
Ese documento ya está adjunto; puede continuar. |
X_CREDITS_INSUFFICIENT |
No hay créditos suficientes; compre en /creditos. |
X_SEND_CONFIRMATION_EXPIRED |
Nadie confirmó el envío en 24 horas; no se envió nada. |
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 y los límites de frecuencia, después de esperar.
Los asistentes tienen la misma lista, en inglés, en la guía docs://guides/errors del servidor MCP.