Reference

Errors

How to read a refusal from Notificado (code, cause and fix) and the codes you will meet most often.

Updated: 2026-09-25

Every refusal has the same three parts:

Part	What it is
`code`	Stable, `X_SCREAMING_SNAKE`. Branch on it, never on the wording.
`cause`	What was wrong, in words.
`fix`	The next step that ends it; usually literal.

Over HTTP they arrive as application/problem+json with a status; over MCP, as a tool result with isError, or as an HTTP answer (401, 413, 429) with the same body.

Common codes

Code	What to do
`X_INPUT_INVALID` / `X_BODY_INVALID`	A field fails the schema; the issues list names each one.
`X_FORBIDDEN`	Your role does not allow the action, or the `orgId` is not your firm's.
`X_CSRF_BLOCKED`	A write with a cookie and no `origin`; see Authentication.
`X_KYC_REQUIRED`	Your lawyer verification is not approved; finish it in the panel.
`X_CASE_RADICADO_TAKEN`	The case already exists; look it up instead of creating another.
`X_CASE_RADICADO_INVALID`	The radicado is not a valid 23-digit number.
`X_NOTIFICATION_NOT_DRAFT`	The notification was already sent; it cannot be edited or re-sent.
`X_NOTIFICATION_NO_RECIPIENTS`	Recipients are missing; add them in the panel.
`X_NOTIFICATION_NO_ATTACHMENTS`	Attach at least one document.
`X_JURAMENTO_REQUIRED` / `X_PROVENANCE_REQUIRED`	An address's sworn statement or provenance is missing.
`X_ATTACHMENTS_TOO_LARGE`	Attachments exceed 20 MB in total.
`X_ATTACHMENT_DUPLICATE`	That document is already attached; carry on.
`X_CREDITS_INSUFFICIENT`	Not enough credits; buy more at /creditos.
`X_SEND_CONFIRMATION_EXPIRED`	Nobody confirmed the send within 24 hours; nothing was sent.
`X_CONSTANCIA_NOT_FOUND`	No constancia yet: it is issued once delivery events arrive.
`X_EVIDENCE_ZIP_NOT_READY`	The package is still being built; retry once after 30 seconds.
`X_MCP_SCOPE_DENIED`	The token lacks that tool's scope.
`X_MCP_RATE_LIMITED`	Too many calls; wait as long as `retry-after` says.

Retries

Never repeat a refused call unchanged. Only *_NOT_READY answers and rate limits are retried, after waiting.

Assistants have the same list in the MCP server's docs://guides/errors guide.